Merciful 1/Merciful - Disc 1.iso/software/d/devpak/devpac.txt

Text File | 1995-10-14 | 180.4 KB | 4,384 lines

                          DEVPAC 2



CHAPTER 1: INTRODUCTION

ALWAYS MAKE A BACK-UP
        Before using Devpac AMIGA you should make a back-up copy of
the original disk and put the original away in a safe place. It is not
copy-protected to allow easy back-up and to avoid inconvenience. This
disk may be backed up using the Workbench or any back-up utility.

        NOTE: The original DEVPAC master disk had a technical support
serial registration number, but you wont get this!.

REGISTRATION CARD
        Enclosed with the manual is a registration card (but not for
you, and you also get a free 68000 Pocket Guide (£2.95 from any
good bookshop.)

THE README FILE
        As with all Hisoft products Devpac AMIGA is continually being
improved and the latest details cannot be included in this manual
may be found in the README.S file on the disk. If you are not already
in th CLI you should wait for any disk activity to stop. Press CTRL
and both AMIGA keys (A software reset), insert your DEVPAC disk. Once
in the CLI this file should be read by entering the command:

type readme (RETURN)

This display can be paused by holding down the menu button on the
mouse.

INTRODUCTION TO THE CLI
        Like most other programming developement tools, DeVPAC AMIGA
is designed to be run from the CLI (Command Line Interface). If you
examine the disk from the Workbench icon interface you won't see many
icons on the disk because of this.
        The CLI is deliberatly hidden from the average user, but as a
programmer you will need to use it, although most of your developement
time will be spent in th DEVPAC programs rather than the CLI.
        DEVPAC disk one is a modified Workbench disk and to start with
you should boot your machine as normal, with a kickstart disk if
required, but when asked for workbench, insert DEVPAC disk one. If you
have already booted from another disk, you should wait for all disk
activity to stop, insert DEVPAC and preform a software reset.
        The CLI is similar in concept to other non-iconic computers,
such as those running MS-DOS or CP/m. It works by you entering
commands such as:

dir (RETURN)

to get a directory of the disk. There is a full description on how to
use the CLI and tutorial in the AMIGA user manuel.

        NOTE: If you have a non-UK keyboard, you may need to modify
your s/startup-sequence file on your DEVPAC back-up disk, although
this may have been done for you! See the readme for more details.

BACKUP DETAILS
        Before making your security backups please ensure your master
disks are write protected. It is recommended the backups made are
regually virus checked with a reliable virus killer, or life could
become very nasty!.

ONE-DRIVE SYSTEMS
        Once you have booted the DEVPAC disk one enter the command

diskcopy df0: to df0: (RETURN)

Then follow the prompts given. The disk to copy from is our write-
protected master disk one the disk to copy to should be a write-
enabled blank disk. Then repeat the procedure with disk two.

TWO-DRIVE SYSTEMS
        Enter the command:

diskcopy df0: to df1: (RETURN)

inset a write-enabled blank disk in the internal drive, and the write-
protected DEVPAC disk one in the external drive and follow the prompts
given. Repeat the procedure with disk two.

MAKING A WORK DISK
        Although you now have a back-up, the disk as supplied dosen't
have room on it for large programs, and it is best to make one or more
work disks when you want to start serious programming. Exactly how you
do this depends on your hardware confuguration.

ONE-DRIVE SYSTEMS
        For single drive users it is best to get rid of as much as you
can fron the DEVPAC disk. Prime candidates are all .info files
together with the printer drivers and keymap files not required.
Deleting Preferances will save space, but this may be useful.
        If you follow these reccomendations the commands required (on
another backup) would be:

cd df0: (RETURN)
delete #?.info (RETURN)
cd devs/printers (RETURN)
dir (RETURN)

This will produce a list of printer drivers. Use the delete command to
erase those you do not need.

cd devs/keymaps (RETURN)
dir (RETURN)

This will produce a list of keymap files. Continue as above.

If space still bets tight you could start deleting the examples
directory, seldom used include files and some commands in the c
directory.

TWO-DRIVE SYSTEMS
        Two drive owners are reccomended to keep the workbench disk
free of all source code, and put such files together with the include
files on the disk in th external drive. The commands to do this (using
another back-up) would be:
        (NOTE: The first command formats a blank disk in the  external
drive losing all data. If you are using a pre-formatted disk you don't
need to do this)

format drive df1: name "source" (RETURN)

Insert a blank disk in the external drive, then press (RETURN) to
format it.

cd df0: (RETURN)
makedir df1:include (RETURN)
makedir df1:examples (RETURN)
copy include to df1:include all (RETURN)
copy examples to df1:examples all (RETURN)
delete include all (RETURN)
delete examples all (RETURN)

        The commands create directories on the external drive for the
example programs and the include files, then delete them from the disk
in the internal drive (which must, of course, be a back-up).

        You will now probably want to copy the program files from
DEVPAC disk two to your workbench disk. To do this insert your back-up
disk two of DEVPAC master disk in df1: and type:

copy df1:c to df0:c all (RETURN)
cd df1: (RETURN)

        This final command changes the default directory to the
external drive so you can edit source files there more easily. It is
often worthwile to build such a command into your startup-sequence.

HARD DISK USERS
        Hard disk users should firstly boot from the hard disk, and
not the DEVPAC workbench disk. Having done this, the DEVPAC disk one
should be placed in the internal drive and the following commands
executed, to copy the programs onto the hard disk:

copy df0:c/genam2 to c: (RETURN)
copy df0:c/monam2 to c: (RETURN)
copy df0:c/genim2 to c: (RETURN)

        Next the two subdirectories should be copied, and this depends
on your requiremants - for example, you may wish to make a seperate
DEVPAC directory on your herd disk. Whatever you choose you will need
to copy the whole of directories "include" and "examples". If you
choose to have a seperate DEVPAC sub-directory the commands would be
(assuming dh0: is the name of your hard disk):

makedir dh0:devpac (RETURN)
copy df0:include to dh0:devpac all (RETURN)
copy df0:examples to dh0:devpac all (RETURN)

        Note that if you put the example directory within another
directory you will have to change the INCDIR directives at the
beginning of them for correct assembly.

        You will also want to copy the following file from your DEVPAC
disk two backup.

copy df0:c/blink to dh0:c

        It probably isn't worth copying the other files until you need
them.

THE DEVELOPMENT CYCLE
        The purpose of DEVPAC is to allow you to enter assembly
language programs, assemble  them to machine-code and debug them if
(or should that be 'when') they don't work. Depending on your
application, you may also be using a linker to join together seperate
modules, possibly with the output from a high level language compiler.
Of course the faster the development cycle, the faster you can get
your programs up and running and DEVPAC was designed to be as fast and
powerful as possible. The link stage is optional, as is the Compile
stage.

DEVPAC DISK CONTENTS
        DEVPAC is supplied on two 3.5" disks, the first a standard
Workbench 1.2 disk, configured to enter the CLI on boot, and the other
contains additional files.

DISK 1
Programs in c directory:
GENAM2 - Screen editor and control program
GENIM2 - Assembler
MONAM2 - Debugger

Other files:
LIBS/LIBFILE.MONAM - Binary file used by debugger
LIBS/ARP.LIBRARY   - Additional library
README             - Latest details about DEVPAC

Additional subdirectories:
INCLUDE  - Contains files for accessing the operating system.
EXAMPLES - The source code to various example programs.

DISK 2
Programs in the c directory:
BLINK     - PD linker
CONVERTFD - FD file conversion utility
CONVERTI  - Include file conversion utility

+ some Workbench files for which there is insufficient room on disk
one.

Text files:
BLINK.DOC - Instructions for linker

Additional subdirectories:
INCLUDE.CBM   - The original Commodore include files with comments
INCLUDE.STRIP - The original Commodore include files without comments
FD.FILES      - The original Commodore fd files. Includes which
                registers are used when calling libraries.
LIBRARY       - Contains amiga.lib, debug.lib
ARP           - Contains parts of Charlie Heaths AmigaDOS replacement
                project (ARP)

HOW TO USE THE MANUAL
     This manual makes no attempt to teach 68000 assembly language
programming or to detail the instruction set.  For the former, the
bibliography  lists  suitable  books,  while for  the  latter  the
supplied  Pocket  Guide is very useful.  The  Appendices  give  an
overview of the technical aspects of the AMIGA but they are not
intended as a complete technical description of the machine.
     This manual is set out in five chapters, this introduction, a
chapter on the screen editor,  a chapter on the macro assembler, a
chapter on the debugger, then a chapter on the linker. In addition
there  are  eight  Appendices  which  detail  various   additional
information.  We suggest you use the manual in a way that  depends
on what type of user you are:

DEVPAC VERSION 1 USERS
Turn  to  Appendix  F and read the  section  describing  the  new
features,  then  read the Reference section of Chapter 4  if  you
intend  using MonAM, as it has changed considerably. You will then
probably want to dip into the manual to read about the new features
that interest you.

BEGINNERS
     If you are a newcomer to assembly language then we  recommend
that you read one of the books in the Bibliography alongside  this
manual.
     At  the end of this chapter there is a simple tutorial  which
you should follow to familiarise yourself with the use of the main
parts of the program suite.
     Chapter  2  details  the editor and is  well  worth  reading,
though much of Chapter 3,  detailing the assembler,  is liable  to
mean  nothing  until you become  more  experienced.  The  Overview
section  of  Chapter 4,  the debugger,  is  strongly  recommended,
though Appendices can be left  for  a  while.
Looking  at the supplied source code may be helpful.

EXPERIENCED USER
     If you are experienced in the use of 68000 assembly  language
but have not used DEVPAC before then here is a very quick way of
assembling a source file:
     Load GENAM2, Press Amiga-L and select your file which will
load into the editor. Press Amiga-A and select the options which you
require  - if generating executable code then click on the  Memory
button  for  additional  speed.  Pressing RETURN  will  start  the
assembler, which may be paused by pressing any key, RETURN resumes.
Any assembly errors will be remembered and on return to the editor
you  will  be placed on the first one.  Subsequent errors  may  be
found by pressing Amiga-J.
     To run your successfully-assembled program (if assembled  to
memory ) press Amiga-X. If assembled to disk, leave the editor and
run it from CLI.
     As  a  quick  introduction  to  the  debugger  the  following
tutorial is recommended.  If you have any problems please read the
relevant section of the manual before contacting us for  technical
support.

A VERY QUICK TUTORIAL
     This  is a quick tutorial intended to let you see  how  quick
and easy it is to edit, assemble and debug programs with DEVPAC.
     In  this tutorial we are going to assemble and run  a  simple
program,  which  contains two errors,  and debug it.  The  program
itself  is  intended to print a message.
     To  run this tutorial you must be in the CLI. If you are not you
should wait for any disk activity to stip, eject all disks, press
(CTRL) and both Amiga keys, and insert the backup of DEVPAC disk one.
It is convenient if we make the current directory the one where our
source program is, with the command:

cd examples (RETURN)

Next load the editor/assembler, by typing:

genam2 (RETURN)

        After a short delay the screen will show an empty window: to
load  the  file you should move the mouse over the PROJECT menu and
hold the right mouse button, and release it on LOAD. A file selector
will then appear and the file we want is called DEMO.S. You should
click on the name to load followed by OK.
     When  the file has loaded the window will show the top  lines
of the file.  If you want to have a quick look at the program  you
may press (SHIFT)-(DOWNCURSOR) or (CTRL)-C to move to the next page.
     With  most  shorter  programs  it is best  to  have  a  trial
assembly  that doesn't produce a listing or binary file  to  check
the syntax of the source and show up any typing errors and so  on.
Move the mouse to the  Program menu and click on Assemble.
     A dialogue box will appear, which should be left alone except
the button near the bottom,  labelled NONE,  should be clicked on.
Click on the Assemble button or press RETURN and the assembly will
begin.
     The   assembler  will  report  an  error,   instruction   not
recognised, and pressing any key will return you to the editor. The
cursor will be placed on the incorrect line and the error  message
displayed in the status line.
     The program line should be changed from MOV.L to MOVE.L so do
this,  then  click on Assemble form the Program menu  again.  This
time  click on the Memory button,  this means the program will  be
assembled  into memory,  instead of onto disk.  This is very  much
faster  and  allows you to try things out  immediately,  which  is
exactly what we want.  Clicking on the Assemble button will  again
assemble  it,  and after you press a key to return to  the  editor
it's ready to run.
     The  assembly  worked this time, but don't run it yet - you will
probably get a software error task held message from the system and
have to reboot the machine.
     The  tool for finding bugs and checking programs is a debugger,
so click on  Debug from the Program menu.  The debugger is described
more fully later, but for now we just want to run the program from the
debugger to 'catch' any problems and find out what causes them, so
press (CTRL)-R.
     After a brief delay the message Address Error will appear at the
bottom  of the display, with the disassembly window showing the
current instruction:

start        MOVE.L    dosname,a1

     This will cause an address error because location dosname is at
an odd address which cannot be accessed with the MOVE.L instruction.
There should be a hash sign before the dosname to put the address of
dosname into the register a1. To return to the editor press (CTRL)-Q,
to ensure that the program will be killed and press Y to terminate the
program and the debugger. We can fix this bug in the source code.
     Press (AMIGA)-T, to go to the top of the file, then click on Find
from the Search menu.  We are going to find the errant instruction
so enter:

             MOVE.L

     Then press Return to start the search. The first occurrence is
the one we are looking for:

start        MOVE.L    dosname,a1

     Ahah! - this is the one, so add a hash to change it to

start        MOVE.L    #dosname,a1

     then assemble it again.  If you click on RUN from the Program
menu you should see the message,  and pressing any key will return
you to the editor.
     Although  the  program  now works we  shall  use  MONAM2,  the
debugger,  to trace through the program,  step by step. To do this
click on Debug from the Program menu, and the debugger will appear
with the message Breakpoint, showing your program.
     There are various windows, the top one displaying the machine
registers, the second a disassembly of the program, the third some
other memory.
     If you look at window 2, the disassembly window, you will see
the current instruction, which in our case is:

start        MOVE.L    #dosname,a1

     As  the  debug was specified in the source code  any  symbols
will appear in the debugger.
     Let's check the area around dosname. Press (AMIGA)-3 and you
should see the window 3's title inverted. Next press (AMIGA)-A and a
dialogue box will appear, asking WINDOW START ADDRESS? - to this
enter:

string

     (it  must  be  in lower-case) and  press  (RETURN).  This  will
re-display  window 3 at the address,  showing the message in  both
hex and ASCII.
     To  execute  this MOVE instruction press  Ctrl-Z.  This  will
execute the instruction then the screen will be updated to reflect
the  new  values of the program counter and register  A1.  If  you
press Ctrl-Z again the MOVEQ instruction will be executed and d0 will
be modified. The next two instructions are the expansion of the
CALLEXECOpenLibrary macro call. Use (CTRL)-z to single step the move
to a6 instruction.

        Next we have:

        jsr     _LVOOpenLiberary(a6)

        This is the call to the exec liberary. All calls to the AMIGAs
operating system have the same form. We don't want to single step this
- we know that amigaDOS works. To treat this system call as one
instruction use (CTRL)-T
        Now single step the next (TST.L d0). D0 should be non-zero; so
the Z flag won't be present in MONAM's register display area.
        Now you can continue to press (CTRL)-z until you get to:

        jsr _LVOOutput(a6)

        This is the call to the DOS.liberary to find our output
handle. Use (CTRL)-T to skip over this. Use (CTRL)-Z to continue
single stepping until we get to:

        jsr     _LVOWrite(a6)

        This is the call that will actually write our string on the
screen - lets make sure that the registers are set up correctly. d1
should have the output handle that came back from the output call in
d0. d2 should have the address of the message. If you look from d2 in
the register display you will see the ASCII bytes of the string. Now
use (CTRL)-T to skip over the Write call. To check that it worked
press the V key, then press any other key to return to monam (being
careful not ot activate any other windows meantime).
        Now all that is left is our de-initialisation. You can use the
(CTRL)-Z and (CTRL)-T commands to step through it as before.
        The last instruction in the program is an RTS. Single stepping
this will terminate Monam, for now, and return to the editor.

CHAPTER 2: SCREEN EDITOR

INTRODUCTION
     To  enter  and assemble your programs you need an  editor  of
some sort and an assembler. GenAM is our editor which loads and runs
the assembler. Genim as required giving the appearance of a full
screen editor and a fast, full specification assembler as one program.
It  also allows  you  to run your assembled programs directly  from
memory without  having  to quit the program or do a disk  access  and
to access a debugger at the press of a key.  The fact that all  these
features  are  combined in one program means that correcting
errors and making changes is as fast as possible without the  need
for slow disk accesses and other programs.
     This chapter details the use of the editor and how to
assemble program  - it does not detail the assembler or the
debugger themselves, they are covered in the following chapters.
     To  run GenAM, enter the command GENAM2 from the CLI. When it has
loaded it will open an empty window, ready for you to enter and
assemble your programs.

THE EDITOR
     A  text  editor is a program which allows you  to  enter  and
alter lines of text, store them on disk, and load them back again.
There  are two types of text editors:  line editors,  which  treat
each  line separately and can be very tricky to  use,  and  screen
editors,  which display your text a screen at a time.  The  latter
tend to be much easier to use.
     The GENAM is a screen editor which allows you to enter and edit
text and save and load from disk, as you would expect. It also lets
you print all or some of your text, search and replace text patterns.
It is intuition based, which means it uses all the user friendly
features of amiga programs that you have become familiar
with on your computer such as windows, menus and mice. However, if
you're a die-hard,  used to the hostile world of computers  before
the  advent of WIMP's,  you'll be pleased to know that you can  do
practically everything you'll want to do from the keyboard without
having to touch a mouse.
     The editor is 'RAM-based',  which means that the file you are
editing stays in memory for the whole time,  so you don't have  to
wait while your disk grinds away loading different sections of the
file  as you edit.  As the amiga can have so much memory, the  size
limitations often found in older computer editors don't exist with
GenAM;  if you have enough memory you can edit files of over  300k
(though make sure your disk is large enough to cope with saving it
if  you do !).
        As all editing operations, including things like searching,
are RAM based they act blindingly quickly. When you have typed in your
program it is not much use if you are unable to save it to disk,  so
the editor has a comprehensive range of save and load options,
allowing you to save all or part of the text and to load other files
into the middle of the current one, for example.
     To  get  things to happen in the editor,  there  are  various
methods available to you.  Features may be accessed in one or more
of the following ways;

     Using a single key, such as a Function or cursor key:

     Clicking on a menu item, such as SAVE:

     Using  a  menu  shortcut,   by  pressing  the right amiga key
     (subsequently  referred  to  as  (amiga))  in  conjunction   with
     another such as (AMIGA)-F for Find:

     Using  the control key (subsequently referred to as Ctrl)  in
     conjunction  with  another,  such as Ctrl-A for  cursor  word
     left:

     Clicking on the screen, such as in the window itself.

     The  menu short cuts have been chosen to be easy and  obvious
to  remember, the cursor key functions are based on those in the
amigaBASIC editor check, while the Ctrl commands are based on those
used  in Wordstar, and many other compatible editors since.
     If  at  any time you get stuck,  pressing the HELP  key  will
bring  up  a comprehensive display of the keys for  functions  not
visible in menus.

A FEW WORDS ABOUT REQUESTERS
        The editor makes extensive use of requesters,  so it  is
worth recapping how to use them,  particularly for entering  text.
The  editor's requesters contains string gadgets and buttons.
        String gadgets enables to enter and edit text, and are
depicted by a box containing the text, and with a block indicating the
cursor position. Characters may be typed in and corrected using the
(BACKSPACE), (DEL), and cursor keys. You can clear the whole edit
field by pressing (AMIGA)-X. Ypu can move the cursor to the beginning
by pressing (SHIFT) and left cursor key, or to the end by (SHIFT) and
right cursor key. If there is more than one editable text field in a
dialog box, you can move between them by clicking near them with the
mouse.
        Buttons  may  be  clicked on with the  mouse  and  cause  the
requester to go away.  Usually there is a default button, shown
by having a double border. Pressing (RETURN) on  the keyboard is
equivalent to clicking on the default button, so long as a string
gadget is active.
        Some requesters allow only a limited range of  characters
to  be  typed into them - for example the Goto Line requester.

THE FILE REQUESTER
        The file requester is used to select file names for the disk
input and output facilities of the editor. In it's simplest form all
you need is to click on the file on the cancel button. At the top of
Requester is the drawer specification, this determines which disk and
sub-directory is displayed and can include wildcards, for example the
specification:

df1:examples/#?.s

will display all files ending in .s. If you edit this specification,
pressing the (RETURN) key will cause the directory to be read and
displayed in the main part of the requester. Files may be selected by
clicking on them and pressing (RETURN) or clicking on OK. The file
list shows sub-directories with the (dir) prefix and the scroll bar
may be used to navigate the file list. Files mey be selected or the
requester cancelled while the directory is still being read! When
initially invoked, only the first fiew files will be displayed. To
update the file listm, click on the slider on the right of the
filename list.
        NOTE: Teh file requester uses the ARP libarary by Charlie
Heath. If this library is not found then a simple string gadget will
be used in it's place, in the same way as GenAm version 1. More
details of the ARP library can be found in the ARP sub-directory on
disk two.

ENTERING TEXT AND MOVING THE CURSOR
     Having loaded GenAM, you will be presented with an empty
window  with a status line at the top and an orange block, which is
the cursor, in the top left-hand corner.
     The  status  line  contains  information  about  the   cursor
position in the form of Line Column offsets as well as the  number
of  bytes of memory which are free to store your  text.  Initially
this  is  displayed as 59980,  as the default text size  is  60000
bytes.  You  may change this default if you  wish,  together  with
various other options,  by selecting Preferences, described later.
The  missing  20  bytes  are  used  by  the  editor  for  internal
information.  The  rest of the status line area is used for  error
messages, which will usually be accompanied with a 'display flash'
to alert you. Any message that get  printed wil  be removed
subsequently when you press a key.
     To enter text,  you type on the keyboard.  As you press a key
it  will  be shown on the screen and the cursor will  be  advanced
along the line.  If you are a good typist you may be able to  type
faster  than  the editor can re-display the  line;  if  so,  don't
worry,  as the program will not lose the keystrokes and will catch
up  when you pause.
        At the end of each line you press the (RETURN) key (or the
Enter key on the numeric pad) to start the next  line. You can correct
your mistakes by pressing the Backspace key, which deletes the
character to the left of the cursor, or the Delete key, which removes
the character the cursor is over.
     The  main  advantage  of a computer editor as  opposed  to  a
normal typewriter,  is its ability to edit things you typed a long
time  ago.  The  editor's large range of  options  allow  complete
freedom to move around your text at will.

CURSOR KEYS
     To move the cursor around the text to correct errors or enter
new characters, you use the cursor keys, (the arrows). If you move
the  cursor  past the right-hand end of the line  this  won't  add
anything to your text,  but it you type some text at the point the
editor  will  automatically add the text to the real  end  of  the
line.  If  you type in long lines the window display  will  scroll
sideways if necessary.
     If  you cursor up at the top of the window the  display  will
either  scroll  down if there is a previous  line,  or  print  the
message  Top of file in the status line.  Similarly if you  cursor
down  off the bottom of the window the display will either  scroll
up if there is a following line, or print the message End of file.
     For those of you used to Wordstar,  the keys Ctrl-S,  Ctrl-D,
Ctrl-E and Ctrl-X work in the same way as the cursor keys.
     To move immediately to the start of the current  line,  press
Ctrl  (left arrow),  to move to the end of the current line  press
Ctrl (right arrow).
     To  move  the cursor a word to the left,  press  Shift  (left
arrow) and to the right press Shift (right arrow). You cannot move
a  cursor past the end of a line with this.  A word is defined  as
anything surrounded by a space,  a tab or a start or end of  line.
The keys Ctrl-A and Ctrl-F also move the cursor left and sight  on
a word basis.
     To move the cursor a page up, you can click on the upper grey
part  of  the vertical scroll bar,  or press Ctrl-R or  Shift  (up
arrow). To move the cursor a page down, you can click on the lower
grey  part  of  the scroll bar,  or press Ctrl-C  or  Shift  (down
arrow).
     If you want to move the cursor to a specific position on  the
screen you move the mouse pointer to the required place and  click
(There is no Wordstar equivalent for this feature!)

TAB KEY
        The Tab key inserts a special character (ASCII code 9) into
your text, which on the screen looks like a number of spaces, but is
rather  different.  Pressing Tab aligns the cursor onto  the  next
'multiple of 8' column,  so if you press it at the start of a line
(column 1) the cursor moves to the next multiple of 8 +  1,  which
is column 9.  Tabs are very useful indeed for making items line up
vertically  and its main use in GenAM is for  making  instructions
line up.  When you delete a tab the line closes up as if a  number
of  spaces had been removed.  The advantage of tabs is  that  they
only  take  up 1 byte of memory,  bat can show on screen  as  many
more, allowing you to tabulate your program neatly. You can change
the  tab size before or after loading GenAM using the  Preferences
command described shortly.

BACKSPACE KEY
     The  Backspace key removes the character to the left  of  the
cursor.  If you backspace at the very beginning of a line it  will
remove  the 'invisible' carriage return and join the line  to  the
end of the previous line.  Backspacing when the cursor is past the
end of the line will delete the last character on the line, unless
the line is empty in which case it will re-position the cursor  on
the left of the screen.

DEL KEY
     The Delete key removes the character under the cursor and has
no effect if the cursor is past the end of the current line.

GOTO A PARTICULAR LINE
     To move the cursor to a particular line in the text, click on
Goto line..  from the Options menu, or press (AMIGA)-G. A requester
will appear allowing you to enter the required line number.  Press
(RETURN) or click on OK button to go to the line or click on  Cancel
to abort the operation.  After clicking on OK the cursor will move
to the specific line,  re-displaying if necessary,  or give  error
End of file if the line does't' exist.

GOTO TO TOP OF FILE
        To  move to the top of the text, click on Goto Top from the
Options  menu,  or  press (AMIGA)-T. The screen will be  re-drawn if
requested.
        NOTE: (AMIGA)-upcurser goes to the previous page not to the
top of file - this has been changed from DEVPAC 1 because some users
found this sequence too easy to hit by mistake.

GOTO END OF FILE
     To  move  the cursor to the start of the very  last  line  of
text, click on Goto Bottom, or press (AMIGA)-B
        NOTE: (AMIGA)-downcursor goes to the next page not to the
bottom of file - this has been changed from DEVPAC 1 because some
users found this sequence too easy to hit by mistake.

QUITTING GENAM
          To leave GenAM, and remove it from memory, click on Quit
from the Project menu, or press (AMIGA)-Q. If changes have been made
to the text which have not  been saved to disk,  an alert box will
appear asking for confirmation. Clicking on Cancel will return you to
the editor, while clicking on OK will discard the changes and return
you to the CLI.

DELETING TEXT

DELETE LINE.
     The  current  line can be deleted from the text  by  pressing
Ctrl-Y.

DELETE TO END OF LINE.
        The text from the cursor position to the end of the current
line can be deleted by pressing Ctrl-Q. (This is equivalent to the
Wordstar sequence Ctrl-Q Y).

UNDELETE LINE
     When a line is deleted using either of the above commands  it
is  preserved in an internal buffer,  and can be re-inserted  into
the text by pressing Ctrl-U,  or the Undo key. This can be done as
many times as required,  particularly useful for repeating similar
lines or swapping over individual lines.

DELETE ALL TEXT
     To clear out the current text, click on Clear from the Project
menu, or press (AMIGA)-C. If you have made any changes to the text
that have not been saved onto the disk, a confirmation is required
and  the  requisite alert box will appear.  Clicking  on  OK  will
delete the text, or Cancel will abort the operation.

DISK OPERATIONS
        It is no use being able to type in text if you are unable to
save it anywhere perminently, or load it back subsequently, so the
editor has a comprehensive set of features to read from and write to
disk.

SAVING TEXT
     To save the text you are currently editing,  click on Save As
from the Project Menu, or press (AMIGA)-S. The File requester
will appear,  allowing you to select a suitable disk and filename.
Clicking  OK or pressing Return will then save the file  onto  the
disk.  If an error occurs a requester will appear showing a sutable
error message, or an AmigaDOS error number, the exact meaning of which
can be found in Appendix A.
     If you click on Cancel the text will not be  saved.  Normally
if  a  file  exists  with the same name it  will  be  deleted  and
replaced  with the new version,  but if Backups are selected  from
the  Preferences  options then any existing file will  be  renamed
with  extension .BAK (deleting any existing .BAK file) before  the
new version is saved.

SAVE
        If you have already done a save as (or a load), GenAm will
remember the name of the file and display it in the title bar of the
window. If you want to save it without having to bother with the file
requester. You can click on save on the Project menu, or press Shift-
(AMIGA)-S, and it will use the old name and save it as above. If you
try to sve without having previously specified a filename you will be
presented with a file requester, as in save as.

LOADING TEXT
     To  load a new file, click on Load from the Project menu, or
press (AMIGA)-L. If you have made any changes that have not been
saved, a confirmation will be required. The file requester will
appear, allowing you to specify the disk and filename. Assuming you do
not cancel, the editor will attempt to load the file. If  it will fit,
the file is loaded into memory and the window is re-drawn. If it will
not fit an alert box will appear warning you, and you should use
preferances to make the edit buffer size larger, then try to load it
again.

INSERTING TEXT
     If  you  want to read a file from disk and insert it  at  the
current  position in your text click on Insert File from the  File
menu or press (AMIGA)-I. The file requester will appear and assuming
that you do not cancel, the file will be read from the disk and
inserted, memory permitting.

CHANGE DIRECTORY
      This command lets you change the current directory that you are
using. Simply uses the file requester to change the directory you
wish.

SEARCHING AND REPLACING TEXT
     To  find a particular section of text click on Find from  the
Search menu,  or press (AMIGA)-F. A dialogue box will appear, allowing
you to enter the Find and Replace strings. If you click on Cancel,
no action will be taken;  if you click Next (or press Return)  the
search will start forwards,  while clicking on Previous will start
the  search backwards.
        If you do not wish to replace, leave the Replace string empty.
If the search was successful, the screen will be re-drawn at that
point with the cursor positioned at the start of the string. If the
search string could not be found, the message Not Found will appear in
the status area and the cursor will remain unmoved. By default the
search is always case-independant, so for example if you enter the
search string as test you could find the words TEST,  Test or test.
If you click on the Upper & Lower case Different button the search
will be case dependant.
     To find the next occurrence of the string click on Find  Next
from  the Search menu,  or press (AMIGA)-N.  The search starts at the
position just before the cursor.
     To search for the previous occurrence of the string click  on
Find Previous from the Search menu, or press (AMIGA)-P.
     Having  found an occurrence of the required text,  it can  be
replaced  with the Replace string by clicking on Replace from  the
Search menu,  or pressing (AMIGA)-R.  Having replaced it,  the  editor
will then search for the next occurrence.
     If  you wish to replace every occurrence of the  find  string
with the replace string from the cursor position onwards, click on
Replace  All from the Search menu.  During the global replace  the
ESC  key  can be used to abort and the status area will  show  how
many  replacements were made.  There is deliberately  no  keyboard
equivalent for this to prevent it being chosen accidentally.
        To search and replace tab characters just press (TAB) when
typing in the dialog box. Other control characters may be searched for
by typing them in directly ((CTRL)-G for example). However do not use
this for CR((CTRL)-M) and LF((CTRL)-J) characters.

BLOCK COMMANDS
     A  Block is a marked section of text which may be  copied  to
another section, deleted, printed or saved onto disk. The function
keys are used to control blocks.
     Block markers remain during all editing commands, moving where
necessary. and are only reset by the commands New, Delete Block, and
Load.

MARKING A BLOCK
     The  start of a block is marked by moving the cursor  to  the
required place and pressing key F1.  The end of a block is  marked
by moving the cursor and pressing key F2. The start and end of the
block do not have to be marked in a specific order - if it is more
convenient you may mark the end of the block first.
     A marked block is highlighted by showing the text in reverse.
While  you  are  editing  a  line that  is  within  a  block  this
highlighting  will not be shown but will be re-displayed when  you
leave that line or choose a command.

SAVING A BLOCK
     Once a block has been marked, it can be saved by pressing key
F3.  If no block is marked,  the message What blocks! will appear.
If  the start of the block is textually after its end the  message
Invalid  block!  will  appear.  Both  errors  abort  the  command.
Assuming  a  valid block has been marked,  the file requester
will appear,  allowing you to select a suitable disk  and
filename.  If  you save the block with a name that already  exists
the  old  version will be overwritten - no backups are  made  with
this command.

COPYING A BLOCK
     A marked block may be copied,  memory permitting,  to another
part of the text by moving the cursor to where you want the  block
copied and pressing key F4. If you try to copy a block into a part
of itself, the message Invalid block will appear and the copy will
be aborted.

DELETING A BLOCK
     A  marked  block  may be deleted from the  text  by  pressing
Shift-F5.  The  shift key is deliberately required to  prevent  it
being  used accidentally.  A deleted block is  remembered,  memory
permitting, in the block buffer, for later use.
        There are two key sequences with this command for
compatibility with both DEVPAC version 2 and DEVPAC version 1.

COPY BLOCK TO BLOCK BUFFER
     The  current marked block may be copied to the block  buffer,
memory permitting,  by pressing Shift-F4.  This can be very useful
for  moving blocks of text between different files by loading  the
first,  marking  the block,  copying it to the block  buffer  then
loading the other file and pasting the block buffer into it.

PASTING A BLOCK
     A  block  in the block buffer may be pasted  at  the  current
cursor position by pressing F5.
    The  block  buffer will be lost if the edit  buffer  size  is
changed or an assembly occurs.

PRINTING A BLOCK
     A  marked  block may be sent to the printer  by  printing  on
Print Block from the File menu, or by pressing (AMIGA)-W. A requester
will appear asking for the name of the printer, which defaults to
PRT:, and clickingon ok will print the block. Of course the name can
be any valid AmigaDOS device, so you could "print" the block to disk
if required. It is differant to Save Block in that tabs are expanded
to spaces.
     If you try to print when there is no block marked,  the whole
file will be printed.

MISCELLANEOUS COMMANDS

HELP SCREEN
        The key equivalents for the commands not found in menus can
be seen by pressing the HELP key, or (AMIGA)-H. A dialogue box will
appear showing the function key uses, the version of GenAm that is
running and the total free memory in the system.

PREFERENCES
     Selecting Preferences..  from the Options menu will produce a
dialogue box allowing you to change several editor settings.

TABS
     By default,  the tab setting is 8, but this may be changed to
any value from 2 to 16.

TEXT BUFFER SIZE
     By default the text buffer size is 60000 bytes,  but this can
be changed from 4000 to 999000 bytes.  This determines the largest
file size that can be loaded and edited,  Care should be taken  to
leave  sufficient room in memory for assembly or running  MonAm.
Changing  the editor work-space size will cause any text  you  are
currently editing to be lost,  so a confirmation is required if it
has not been saved.

BACKUPS
     By  default the editor doesn't make backups of programs  when
you  save them,  but this can be turned on by clicking on the  Yes
radio button.

AUTO INDENTING
     It can be particularly useful when editing programs to indent
subsequent  lines from the left,  so the editor supports an  auto-
indent mode.  When active, an indent is added to the start of each
new line created when you press RETURN. The contents of the indent
of  the new line is taken from the white space (i.e.  tabs  and/or
spaces) at the start of the previous line.

END OF LINE
     By default (i.e. when Stop is selected) when you press cursor
left at the beginning of a line or cursor right at the end of line the
cursor does not move. Changing this item to wrap causes the cursor to
move to the previous line if you press cursor left at the beginning
and to the next line if you press curser left at the beginning and the
next line if you presscursor right at the end. The best way to find
out which you prefer is to try using both settings.

LOAD MONAM
     By  default  a  copy of MonAM is  loaded  during  the  editor
initialisation,  allowing it to be accessed at the press of a key.
Should  this not be required it can be disabled with this  option.
This will save around 24k of memory.  The new value of this option
will  only  have  an effect if you save the  preferences  and  re-
execute the editor.

AUTOSIZE WINDOW
     By default, Genam will not use the entire screen display, but if
this is selected then it will make it's initial window as large as
possible.

SAVING PREFERENCES
     If  you click on the Cancel button any changes you make  will
be ignored.  If you click on the OK button the  changes  specific
will remain in force until you quit the editor.  If you would like
the  configuration made permanent then click on the  Save  button,
which will create the file GENST2.INF on your disk.  Next time you
run GenST the configuration will be read from that file in the current
directory. In  addition to saving the editor configuration  the
current setting from the Assembly Options dialogue box are also saved.
If the .INF file is not found in the current directory when the editor
is loaded, the c: directory is also searched. This allows a global
settings as well as specific local ones.

ASSEMBLING & RUNNING PROGRAMS
     All assembly and run options can be found on the Program menu

ASSEMBLY
     To  assemble the program you are currently editing  click  on
Assemble from the Program menu, or press (AMIGA)-A. The meaning of the
various  options,  together  with the assembly process  itself  is
detailed in the next chapter.  The only option covered here is the
Output option.
     GenAM  can  assemble  to  disk,   to  memory,  or  nowhere  -
assembling to nowhere is ideal for syntax checking while  assembly
to  memory is much faster than to disk and good for trying  things
out quickly.
     If you assemble to disk and you haven't saved your program source
code yet the file will be based on the name NONAME.
     After  you  click on Assembly or press  RETURN  the  assembly
process will start,  describe more fully in the next  chapter.  At
the  end  of the assembly the program will wait for a  key  press,
allowing you to read any messages produced,  before returning  you
to the editor.  If there were any errors the editor will go to the
first  erroneous line and display the error message in the  status
bar.  Subsequent  errors  (and warnings) may  be  investigated  by
pressing (AMIGA)-J.

RUNNING PROGRAMS
     If you click on Run or press (AMIGA)-X (eXecute) you can then run
a  program  previously assembled into memory.  When  your  program
finishes it will return you to the editor.  If the assembly didn't
complete  normally for any reason then it is not possible  to  run
the program.
     If  your  program crashes badly you may never return  to  the
editor, so if in doubt save your source code before using this, or
the following command.
     If  only non-fatal errors occurred  during  assembly  (e.g.
undefined  symbols)  you  will  still be  permitted  to  run  your
program, at your own risk.

DEBUG
     If you wish to debug a program previously assembled to memory
click  on Debug form the Program menu, or press (AMIGA)-D. This will
invoke  MonAM to  debug your  program,  including  any  debugging
information specified.  Pressing Ctrl-C from MonAM will  terminate
the debugger.
     If  the  Load  MonAM option is disabled this  option  is  not
available and the menu is disabled.

MONAM
     Clicking on MonAM from the Program menu, or pressing (AMIGA)-M,
will invoke MonAM in a similar way to if it was invoked by typing it's
name in CLI, but instantly, as it  is  already  in  memory.  You will
return  to  the  editor  on termination of the debugger.
     If  the  Load  MonAM option is disabled this  option  is  not
available and the menu is disabled.

JUMP TO ERROR
     During  an  assembly any warnings or errors  that  occur  are
remembered,  and can be recalled from the editor. Clicking on Jump
to  Error from the Program menu,  or pressing (AMIGA)-J will move  the
cursor  to the next line in your program which has an  error,  and
display  the  message in the status line of the  window.  You  can
step to the next one by pressing (AMIGA)-J again,  and so on,  letting
you  correct errors quickly and easily.  If there are  no  further
errors when you select this option the message No more errors will
appear,  or if there are no errors at all the message What errors!
will appear.

THE EDITOR WINDOW
        The window used by the editor works like the most other Amiga
windows, so you can move it around by using the drag gadget on the top
of it, you can change it's size by dragging on the size gadget and
control it's position relative to the other windows by using the front
and back gadgets. Clicking on the close gadget is equivelant to
choosing Quit fron the project menu. Like all intuition windows, it
has to be active for you to be able get at it's menu items. If you
have a larger than normal screen size (eg. a european PAL system which
has 256 vertical lines) you can re-size the window to be the full size
of your screen.
        When GenAm is busy doing a disk access or assembly the cursor
changes to an hourglass and all menu items are made grey.
        NOTE: When using GenAm (And MonAm) on PAL machines with
external RAM, you may sometimes get two mouse pointers; one will be
the normal intuition pointer, the other will be the custom pointer
allocated with the program you are using. Do not be alarmed - this
seems to be a harmless bug in intuition.

SYSTEM REQUESTERS
        When a system requester appears from the editor (eg. File not
found), pressing any key is equivelant to clicking on cancel.

CHAPTER 3: MACRO ASSEMBLER

INTRODUCTION
     GenAM is a powerful,  fast,  full  specification  assembler,
available  instantly  from within the editor or as a  stand  alone
program.  It  converts the text typed or loaded into  the  editor,
optionally  together  with the files read from the  disk,  into  a
binary file suitable for immediate execution or linking, or into a
memory image for immediate execution from the editor.

INVOKING THE ASSEMBLER

FROM THE EDITOR
     The  assembler  is  invoked from the editor  by  clicking  on
Assemble from the Program menu,  or by pressing (AMIGA)-A.  A dialogue
box will appear which looks like this (almost);

|------------------------------------------------|
| Program type   Executable    Linkable          |
| Symbols case   Dependant     Independant       |
| Debug info     None    Normal   Exports        |
| List           None  Screen  Printer  Disk     |
| Assembly       Fast          Slower            |
| Output to      None          Memory            |
|       ______________________________________   |
| Disk |______________________________________|  |
|                Assembly options                |
| Cancel                        Assemble         |
| _______________________________________________|

     PROGRAM  TYPE This lets you select between executable or
linkable format  output.  The differences between these  are  detailed
later.

     SYMBOLS  CASE  This lets you select whether labels  are  case
dependant or not. If case Dependant is selected then Test and test
would  be different labels,  if the case Independant  is  selected
then they would be the same.

     DEBUG  INFO  If  you wish to debug your  program  using  your
original  symbols you can select Normal or Extended  debug  modes.

     LIST  selecting Printer will divert the assembly listing to the
PRT: device, or selecting Disk will send the listing to a
file based on the source filename, but with the extension .LST.

     ASSEMBLER  Normally this option should be left as fast selected,
but if the assembler runs out of memory select slower. Selecting
Slower forces the assembler to use little memory as possible thus
slowing down things like reading include files.

     OUTPUT TO This lets you select where the output file is to be
created. None means it is 'thrown away', ideal for syntax checking
a program;  Memory means it is assemble into a buffer allowing  it
to be run or debugged instantly form the editor without having  to
create  a  disk  file:  Disk means a file  will  be  created.  The
selection  of the name of this file can be left to the  assembler,
using rules described shortly.
     The  first  two options may be specified in the  source  file
using the OPT directive.
     Having selected your required options you should click on the
Assemble  button (or press Return) to start the assembly.  At  the
end of assembly you should press any key to return to the  editor.
If any errors occurred the cursor will be positioned on the  first
offending line.

STAND ALONE ASSEMBLER

COMMAND LINE FORMAT
     The assembler, Genim2, may by invoked directly from the CLI.
The command line should be the form:

GenIm2   mainfile    <-options>  [-options]

     The  mainfile  should  be  the name  of  the  file  requiring
assembly and if no extension is specified defaults to ,S.  Options
should  follow  this  donated by a -  sign  then  an  alphabetical
character.   Allowed   options  are  shown  below  together   with
equivalent OPT directives :

     B    no binary file should be created

     C    case insensitive labels (OPT C-)

     D    debug (OPT D+)

     I    specify include directory (follow immediatly with path)

     L    linkable code (OPT L+)

     M    use slow(low memory) assembly mode. See above. Not the
          same as OPT m+

     O    specify output filename (follows immediately after O)

     P    specify  listing  filename  (should  follow  immediately
          after P) defaults to source filename with extension .LST

     Q    pause for key press after assembly

     T    specifies the tab setting for listing. For example -T10
          uses a tab setting of 10.

     X    used when generating linkable code to export only the
          exported (XDEFed) symbols (OPT X+)

     NOTE: The options used by GenIm2 are rather differant to those
used in DEVPAC version 1 but the same as DEVPAC version 2.

        The default is to create an executable binary file with  the
name based on the source file and output file type,  no  listing,
with no case sensitive labels. For example,

genim2    test  -b

assembles test.s with no binary output file

genim2    test  -oram:test -p -iminc/

assembles test.s into a binary file ram:test.prg and a listing  file
to test.lst, with an include directory of myinc.

genim2    test  -ldppprt:

assembles  test.s into linkable code with debug and a  listing
to  the printer as set using the Amiga Preferances tool.

OUTPUT FILENAME
     GenAM  has  certain rules regarding the  calculation  of  the
output filename, using a combination of that specified at assembly
time  (either in the Disk: string gadget in the requester) or
using the -O option on the command line) and the Output directive:
     If an output filename is explicitly given at assembly time then:
     name = explicit filename

else:
     if the Output directive has not been used then
          name = source filename without an extension or .O
     else if the Output directive specifies an extension then
          name = source filename + extension in Output
     else
          name = name in Output

ASSEMBLY PROCESS
     GenAM is a two-pass assembler; during the first pass it scans
all  the text in memory and from disk if required,  building up  a
symbol  table.  If  syntax  errors are found  on  the  first  pass
assembly these will be reported and assembly will stop at the  end
of  the  first  pass,   otherwise,  during  the  second  pass  the
instructions are converted into bytes,  a listing may be  produced
if required and a binary file can be created on the  disk.  During
the  second  pass any further errors and warnings will  be  shown,
together with a full listing and symbol table if required.
     During assembly, any screen output can be paused by holding down
the right mouse button or, when using the stand alone assembler, by
pressing  any key (pressing (RETURN) will  resume it).  Assembly  may
be  aborted  by pressing Ctrl-C, although doing so will make any
binary file being created  invalid  as  it  will be incomplete  and
should  not  be executed.

ASSEMBLY TO MEMORY
        To reduce development time GenAM can assemble  programs  to
memory, allowing immediate execution or debugging from the editor.
        A  program running from memory is just like any other  normal
AmigaDOS  program and should terminate using an RTS instruction with
the stack as the program was entered.
       Programs should be careful if they self-modify as a re-executed
program will be in its original state. The state is left as when the
program was previously executed.
       The current assembly options can be made the default on re-
loading the editor if Save Preferences is used.

BINARY FILE TYPES
     There are two types of binary files which may be produced  by
GenAM, for different types of applications. They are distinguished
by the extension on the filename:
     If there is no extension then this is a directly executable file,
or if the extension is .o or .obj then this is an AmigaDOS linkable
file.
     Actually there are two sorts of executable files; those that are
designed to be run from the CLI and those that are designed to be run
from workbench. The differance is in the code that is part of the
program; the assembler cannot tell the differance. This is described
later.
     .o files cannot be run immediatly, but have to be read into a
linker, usually with other sections, and are known as linkable object
modules.

TYPES OF CODE
    Unlike  most 8-bit operating systems,  but like  most  16-bit
systems,  an executable program under AmigaDOS will not be loaded at
a  particular  address  but,  instead,  be loaded  at  an  address
depending on the exact free memory configuration at that time.
     To get around the problem of absolute addressing the ST  file
format includes relocation information allowing GEMDOS to relocate
the  program  after it has loaded it but before  running  it.  For
example the following program segment:

               move.l #string, a0
               .
               .
               .
     string    dc.b   'Press any key',0

places the absolute address of string into a register, even though
at  assembly  time the real address of string cannot  possibly  be
known.  Generally  the programmer may treat addresses as  absolute
even though the real addresses will not be known to him, while the
assembler  (or  linker) will look after the  necessary  relocation
information.
    NOTE: For certain programs, normally games or cross machine
development an absolute address may be required,  for this  reason
the ORG directive is supported.

The syntax of the assembler will now be described.

ASSEMBLER STATEMENT FORMAT
     Each  line  that is to be processed by the  assembler  should
have the following format;

     Label     Mnemonic       Operand(s)          Comment
     Start     move.l         d0,(a0)+            store the result

     Exceptions  to  this  are  comment  lines,  which  are  lines
starting with an asterisk or semi-colon,  and blank  lines,  which
are  ignored.  Each field has to be separated from the  others  by
white space - any number or mixture of space and tab characters.

LABEL FIELD
     The label should normally start at line 1,  but if a label is
required  to start at another position then it should be  followed
immediately   by  a  colon  (:).   Labels  are  allowed   on   all
instructions, but are prohibited on some assembler directives, and
absolutely  required  on  others.  A  label  may  start  with  the
characters A-Z,  a-z,  or underline (_),  and may continue with  a
similar  set together with the addition of the digits 0-9 and  the
period (.).
     Labels  starting with a period are  local  labels,  described
later. Sequances of digits terminated by a $ are also labels. Macro
names and register equate symbols may not have periods in them,
though macro names may start with a period. By default the first 127
characters of labels are significant, though this can be reduced if
required.  Labels should not be the same as register names, or the
reserved words SR, CCR or USP.
     By default labels are case-sensitive though this may be changed.

     Some example legal labels are ;

test, Test, TEST, _test, _test.end, test5, _5test

     Some illegal labels are;

     5test, _&e, test>,

     There  are  certain reserved symbols  in  GenST,  denoted  by
starting with two underline characters.  These are __LK,  __RS and
__G2.

MNEMONIC FIELDS
     The  mnemonic  field  comes after the  label  field  and  can
consist  of 68000 assembler instructions,  assembly directives  or
macro  calls.  Some  instructions  and  directives  allow  a  size
specifier,  separated from the mnemonic by a period. Allowed sizes
are .B for byte,  .W for word, .L for long and .S for short. Which
size specifiers are allowed in each case depends on the particular
instruction or directive.  GenAM is case-sensitive to mnemonic and
directive names, so Move is the same as move and the same as mOvE,
for example.

OPERAND FIELD
     For those instructions or directives which require  operands,
this field contains one or more parameters,  separated by  commas.
GenST is case-sensitive regarding register names so they may be in
either or mixed case.

COMMENT FIELD
     Any  white space not within quotes found after  the  expected
operand(s)  is  treated  as a delimiter before the  start  of  the
comment, which will be ignored by the assembler.

EXAMPLES OF VALID LINES

               move.l  d0,(a0)+         comment is here

     loop      TST.W       d0

     lonely.label

        rts

* this is a complete line of comment

; and so is this

     indented: link A6,#-10 make room

a_string: dc.b 'spaces allowed in quotes' a string

EXPRESSIONS
     GenAm allows complex expressions and supports full  operator
precedence, parenthesis and logical operators.
     Expressions are in two types -absolute and relative - and the
distinction is important. Absolute expressions are constant values
which are known at assembly time. Relative expressions are program
addresses  which  are  not known at assembly-time  as the AmigaDOS
loader  can  put  the  program where  it  likes  in  memory.  Some
instructions and directives place restrictions on which types  are
allowed  and  some  operators cannot be used  with  certain  type-
combinations.

OPERATORS
     The operators available, in decreasing order of precedence, are:
     monadic minus (-) and plus (+)
     bitwise not (~)
     shift left (<<) and shift right (>>)
     bitwise And (&), Or (!), and Xor (^)
     multiply (*) and divide (/)
     addition (+) and subtraction (-)
     equality (=), less than (<), greater than (>)

     The comparison operators are signed and return 0 if false  or
-1  ($FFFFFFFF) if true.  The shift operators take the  left  hand
operand and shift it the number of bits in the right hand  operand
and vacated bits are filled with zeros.

     This precedence can be overridden by the parentheses ( and ).
With operators of equal precedence, expressions are evaluated from
left-to-right.  Spaces  in  expressions (other than  those  within
quotes  as ASCII constants) are not allowed as they are  taken  as
the separator to the comment.

     All expression evaluation is done using 32-bit signed-integer
arithmetic, with no checking of overflow.

NUMBERS
     Absolute numbers may be in various forms;

          decimal constants, e.g. 1029
          hexadecimal constants, e.g. $12f
          octal constants, e.g. @730
          binary constants, e.g. %1100010
          character constants, e.g. 'X'

     $ is used to denote hex numbers,  % for binary,  @ for  octal
and single ' or double quotes " for character constants.

CHARACTER CONSTANTS
     Whichever  quote is used to mark the start of a  string  must
also  be used to denote its end and quotes themselves may be  used
in  strings delimited with the same quote character by  having  it
occur  twice.  Character  constants can be upto  4  characters  in
length and evaluate to right-justified longs with null-padding  if
required.  For example, her are some character constants and their
ASCII and hex values:

     "Q"       Q              $00000051
     "hi"      hi             $00006869
     "Test"    test           $54657374
     "it's"    it's           $6974277C
     'it''s'   it's           $6974277C

     Strings  used  in DC.B statements follow  slightly  different
justification rules, detailed with the directive later.

     Symbols  used  in  expressions will  be  either  relative  or
absolute,  depending on how they were defined.  Labels within  the
source  will  be  relative,  while those  defined  using  the  EQU
directive  will be the same type as the expression to  which  they
are equated.
     The  use of an asterisk (*) denotes the value of the  program
counter at the start of the instruction or directive and is always
a relative quantity.

ALLOWED TYPE COMBINATIONS
     The  table below summarises for each operator the results  of
the various type combinations of parameter an d which combinations
are  not allowed.  An R denotes a Relative result,  an  A  denotes
absolute  and a * denotes that the combination is not allowed  and
will produce an error message if attempted.

                    A op A   A op R   R op A   R op R
Shift operators       A        *        *         *
Bitwise operators     A        *        *         *
Multiply              A        *        *         *
Divide                A        *        *         *
Add                   A        R        R         *
Subtract              A        *        R         A
Comparisons           A        *        *         A

ADDRESSING MODES
     The available addressing modes are shown in the table  below.
Please   note  that  GenST  is  case-insensitive   when   scanning
addressing modes, so D0 and a3 are both valid registers.

FORM      MEANING                                 EXAMPLE
Dn        data register direct                    D3
An        address register direct                 A5
(An)      address register indirect               (A1)
(An)+     address reg indirect + post-increment.  (A5)+
-(An)     address reg indirect + pre-increment.   -(A0)
d(An)     address reg indirect with displacement  20(A7)
d(An,Rn.s)address register indirect with index    4(A6,D4.L)
d.W       absolute short address                  $0410.W
d.L       absolute long address                   $12000.L
d(PC)     program counter relative with offset    NEXT(PC)
d(PC,Rn.s)program counter relative with index     NEXT(PC,A2.W)
#d        immediate data                          #26

n         denotes register number from 0 to 7
d         denotes a number
R         denotes index register, either A or D
s         denotes size, either W or L, when omitted defaults to W

When  using address register indirect with index the  displacement
may be omitted, for example

move.l    (a3,d2.l),d0

will assemble to the same as

move.l    0(a3,d2.l),d0

SPECIAL ADDRESSING MODES

CCR       condition code register
SR        status register
USP       user stack pointer

In  addition to the above,  SP can be used in place of A7  in  any
addressing mode, e.g. 4(SP,D3.W)
     The data and address registers can also be denoted by use  of
the reserved symbols R0 through R15. R0 to R7 are equivalent to D0
to D7,  R8 to R15 are equivalent to A0 to A7. This is included for
compatibility with other assemblers.

LOCAL LABELS
     GenAm supports local labels,  that is labels which are  local
to  a  particular area of the source code.  These are  denoted  by
starting  with  a period and are attached to  the  last  non-local
label, for example;

lenl      move.l    4(sp),a0
.loop     tst.b     (a0)+
          bne.s     .loop
          rts
len2      move.l    4(sp),a0
.loop     tst.b     -(a0)
          bne.s     .loop
          rts

    There  are  two labels called .loop in this code segment but the
first is attached to lenl, the second to len2.
    If you wish to use global labels starting with a dot you may use
OPT U+ to allow this and make the underline character introduce local
labels.
    The local labels .W and .L are not allowed to avoid confusion with
the absolute addressing syntax.

AMIGA MACRO ASSEMBLER LOCAL LABELS
    You may also use strings of decimal digits terminated by the $
sign as local labels. This facility has been provided for
compatability with other assemblers; we reccomend the use of form
shown above as this makes programs much more readable.

SYMBOLS AND PERIODS
     Symbols which include the period character can cause problems
with GenAm due to absolute short addressing.
     The Motorola standard way of denoting absolute short addresses
causes  problems as periods are considered to be part of a  label,
best illustrated by an example:

          move.l    vector.w,d0

where vector is an absolute value, such as a system variable. This
would  generate an undefined label error,  as the label  would  be
scanned as vector.w.  To get around this,  the expression, in this
case a symbol, may be enclosed in brackets, e.g.

          move.l    (vector).w,d0

though the period mat still be used after numeric expressions, e.g.

          move.l    $4.w,d0

    NOTE: GenAm version 1 also supported the use of \  instead  of  a
period to denote short word addressing and this is still supported
in this version,  but this is not recommended due to the potential
for \W and \L to be mistaken for macro parameters.

INSTRUCTION SET

WORD ALIGNMENT
     All  instructions  with the exception of DC.B  and  DS.B  are
always  assembled on a word boundary.  Should you require  a  DC.B
explicitly on a word boundary,  the EVEN directive should be  used
before  it.  Although all instructions that require it  are  word-
aligned,  labels with nothing following them are not word  aligned
and can have odd values. This is best illustrated by an example;

          nop                 this is always word aligned
          dc.b      'odd'
start
          tst.l     (a0)+
          bne.s     start

The  above  code would not produce the required  result  as  start
would have an odd value.  To help in finding such an  instructions
the assembler will produce an error if it finds an odd destination
in a BSR or BRA operand. Note that such checks are not made on any
other  instructions,  so it is recommended that you  precede  such
labels  with  EVEN  directives if you require  them  to  be  word-
aligned.  A  common error is deliberately not to do this,  as  you
know  the preceding string is an even number of  bytes  long.  All
will be well until the day you change the string...

INSTRUCTION SET EXTENSIONS
     The  complete 68000 instruction set is supported and  certain
shorthands are automatically accepted,  detailed below. A complete
description of the instruction set including syntax and addressing
modes can be found in any 68000 reference guide or in the supplied
pocket guide.

CONDITION CODE
The altenate condition codes HS and LO are supported in Bcc, DBcc
and Scc instructions, equivalent to CC and CS, respectively.

BRANCH INSTRUCTIONS
     To force a short branch use Bcc.B or Bcc.S,  to force a  word
branch  use  Bcc.W or to leave the optimiser  use  Bcc.  Bcc.L  is
supported for compatibility with GenAm 1 with a warning as it  is,
strictly  speaking,   a  68020  instruction.   A  BRA.S  to   the
immediately following instruction is not allowed and is converted,
with  a warning,  to a NOP.  A BSR.S to the immediately  following
instruction is not allowed and will produce an error.

BTST INSTRUCTION
     BTST is unique among bit-test instructions in supporting  PC-
relative addressing modes.

CLR INSTRUCTION
     CLR An is not allowed,  use SUB.L An,An instead (though  note
that the flags are not affected).

CMP INSTRUCTION
     If  the source is immediate then CMPI is used,  else  if  the
destination is an address register then CMPA is used, else if both
addressing modes are post-incremented then CMPM is used.

DBcc INSTRUCTION
     DBRA is accepted as an equivalent to DBF.

ILLEGAL INSTRUCTION
     This generates the op-cope word $4AFC.

LINK INSTRUCTION
     If the displacement is positive or not even a warning is given.

MOVE FROM CCR INSTRUCTION
     This  is a 68010 and upwards instruction,  converted  with  a
warning to MOVE from SR.

MOVEQ INSTRUCTION
     If the data is in the range 128-255 inclusive a warning  will
be  given.  It  may be disabled by specifying a long size  on  the
instruction.

ASSEMBLER DIRECTIVES
     Certain  pseudo-mnemonics  are  recognised  by  GenIm.  These
assembler  directives,  as  they are called,  are  not  (normally)
decoded into opcodes, but instead direct the assembler time. These
actions have the effect of changing the object code  produced,  or
the  format of the listing.  Directives are scanned  exactly  like
executable  instructions and some may be preceded by a label  (for
some  it is obligatory) and may be followed by a comment.  If  you
put  a  label on a directive for which it  is  not  relevant,  the
result  will  be undefined but will usually result  in  the  label
being ignored.
     Each  directive will now be described in  turn.  Please  note
that  the case of a directive name is not important,  though  they
generally are shown in upper case. The use of angled brackets ( <> )
in descriptions denote optional  items,  ellipses  (  ...  )
denote repeated items.

ASSEMBLY CONTROL

END
     This directive signals that no more text is to be examined on
the current pass of the assembler. It is not obligatory.

INCLUDE filename
     This directive will cause source code to be taken from a file
on  disk  and assembled exactly as though it were present  in  the
text.  The  directive  must be followed by a  filename  in  normal
AmigaDOS format.
     If the filename has a space in it the name should be enclosed
in  single  or double quotes.  A drive  specifier,  directory  and
extension may be included as required, e.g.

     include b:constants/header.s

     Include  directives may be nested as deeply as memory  allows
and  if any error occurs when trying to open the file or read  it,
assembly will be aborted with a fatal error.
     If  no  drive or path name is specified,  that  of  the  main
source file will be used when trying to open the file.

     NOTE: The more memory the better, GenAm will read the whole of the
file in one go if it can and not bother to re-read the file during
pass 2.

INCDIR "directory"<,"directory" etc.>
     This directive specifies a list of directories that the include
directive should search in order to find each file. GenIm will append
each string onto the front of that given in the include directive. This
directive must appear before any include directives.

INCBIN    filename
     This  takes a given binary file and  includes  it,  verbatim,
into the output file.  Suggested uses include screen data,  sprite
date and ASCII files.
     The included data is forced to an even boundary and a single null
character is appended if the file is an odd number of bytes in length.

OPT       option <,option>...
     This  allows  control over various options within  GenAm  and
each one is denoted by a single character normally followed by a +
or - sign. Multiple options may be specified, separated by commas.
The allowed options are:

OPTION A - AUTOMATIC PC MODE ADDRESSING
     If OPT A+ is specified then GenAm will use PC mode addressing
where possible. For example:

          move.l    int_in,d0

will automatically be transformed into

          move.l    int_in(pc),d0

when assembled.

     Use of this option can significally reduce program size and
running time without a lot of extra typing. Please note however thit
it does not guarentee that the code generated will be position
independant.
     If you need to over-ride the automatic use of PC mode then use
the form (expression).l in a similar manner to that of short word
addressing as described above under labels and periods.
     So the example above could be forced to use absolutre addressing
by using the following:

move.l     (int_in).l,d0

    The default is A- when no such transformations are performed.

OPTION C - CASE SENSITIVITY AND SIGNIFICANCE.
     By default,  GenAm is sensitive to label case and labels  are
significant to 127 characters.  This can be overridden , using  C-
for case-sensitivity or C+ for case-insensitivity. The significan
ce  may be specified by specifying a decimal number between the  C
and  the sign,  for example C16+ denotes case  insensitive  labels
with  16 character significance.  This option may be used  at  any
time  in  a  program but normally only makes  sense  at  the  very
beginning of a source file.

OPTION D - DEBUGGING INFORMATION
     The  AmigaDOS  binary file format supports the inclusion of a
symbol hunk, which may be read by debuggers such  as
MONAm and  can be extremely useful when  debugging  programs.  By
default  this is switched off but it may be activated with D+  and
de-activated with D-. Normally all the relative symbols are included
in the file, but if OPT X+ is used in linkable mode then only the
exported (XDEF) symbols will be included.

OPTION L - LINKER MODE.
     The  default for GenAM is to produce executable code  but  L+
will  make it produce AmigaDOS linkable code, or L- will make it
revert to executable. This directive must be the very first line, in
the first text file.

OPTION M - MACRO EXPANSIONS.
     When an assembly listing is produced,  macro calls are  shown
in  the same form as in the source.  If you wish the  instructions
within  macros to be listed,  use M+,  while M- will  disable  the
option. You can use this directive as often as required. M- is the
default.

OPTION O - OPTIMISING.
     GenAM is capable of optimising certain statements to  faster
and  smaller versions.  By default all optimising is off but  each
type  can  be  abled and disabled as  required.  This  option  has
several forms:

OPT  O1+       will optimise backward branches to short if  within
               range, can be disabled with O1-.

OPT  O2+       will   optimise  address  register  indirect   with
               displacement addressing modes to addresss  register
               indirect,  if the displacemant evalues to zero, and
               can be disabled with O2-. For example,

          move.l   next(a0),d3

will be optimised to

          move.l   (a0),d3

If the value of next is zero.

OPT O+         will turn all optimising on.

OPT O-         will turn all optimising off.

OPT O1-, OPT O2-    will disable the relevant optimisation.

OPT OW-        will disable the warning messages generated by each
               optimisation, OW+ will enable them.

     If any optimising has been done during an assembly the number
of optimisations made and bytes saved will be shown at the end  of
assembly.

OPTION P - POSITION INDEPENDANT CHECKS.
     With  this  enabled with P+ GenAM will check  that  all  code
generated is position-independant,  generating errors on any lines
which require relocation.  It can be disabled with P- and defaults
to off.

OPTION S - SYMBOL TABLE
     When  a listing is turned on a symbol table will be  produced
at the end.  If you wish to change this S- will disable it,  while
S+ will re-enable it.  If you use this directive ore than once  the
last one will be taken into account.

OPTION T - TYPE CHECKING.
     GenST  can  often spot programming errors as  it  checks  the
types of certain expressions.  For some applications or styles  of
programming  this can be more of a hindrance than a  help.  So  T-
will  turn checks off.  T+ turning them back on.  For example  the
program segment

     main      bsr            initialise
               lea            main(a6),a0
               move.l         (main).w,a0

     will  normally  produce  an  error  as  main  is  a  relative
expression  where as the assembler expects an absolute  expression
in both cases.  However if this code is designed to run on another
68000  machine this may be perfectly valid,  so the type  checking
should be disabled.

OPTION U - UNDERLINES FOR LOCAL LABELS
     Option U+ changes the character that introduces local tables to
be underline (_) rather than dat (.). Usa this if you need to use
labels beginning with dot for non-local labels.

OPTION W - WARNINGS
     If  you wish to disable the warnings that GenST can  produce,
you can do so with W-.  To re-enable them use W+.  This  directive
can be used as often as required.

OPTION X - EXPORTDEBUG
     This is a special version of option D which only outputs the
exported (XDEFed) symbols when producing linkable code. See the D
option above.

OPTION SUMMARY
     The  defaults  are  shown  in  brackets  after  each  options
description;

A    automatic PC mode addressing
C    case-sensitivity and significance (C127+)
D    include debugging info, (D-)
L-   produce executable code (default)
L+   produce GST linkable code
M    expand macros enlisting (M+)
O    optimising control (O-)
P    position independant code checks (P-)
S    symbol table listing
T    type checking (T+)
W    warning control (W+)
X    export debug (X-)

For example -   opt  m+,s+,w-

will  turn macro expansion on,  enable the symbol table  list  and
turn warnings off.

<label> EVEN
     This  directive  will force the program counter to  be  even,
i.e.   word  aligned.   As  GenAM automatically  word-aligns  all
instructions (except DC.Bs and DS.Bs).  It should not be  required
very often but can be useful for ensuring buffers and strings  are
word-aligned when required

CNOP      offset,alignment
This  directive  will align the program counter  using  the  given
offset  and alignment.  An alignment of 2 means  word-aligned,  an
alignment of 4 means long-word-aligned and so on. The alignment is
relative to the start of the current section. For example,

          cnop   1,4

aligns  the  program  counter  a  byte  past  the  next  long-word
boundary.

     Some parts of the Amiga operating system require certain items to
be longword aligned and this can be achieved with:

          cnop   0,4

     The start of a program and of each section is always guaranteed
to be longword aligned.

<label>   DC.B      expression<,expression> ...
<label>   DC.W      expression<,expression> ...
<label>   DC.L      expression<,expression> ...

     These  directives define constants in memory.  They may  have
one or more operands,  separated by commas.  The constants will be
aligned  on  word boundaries for DC.W and DC.L no  more  than  128
bytes can be generated by a single DC directive.
     DC.B  treats  strings slightly different to those  in  normal
expressions.  While the rules described previously about quotation
marks still applies.  No padding of the bytes will occur,  and the
length of any string can be upto 128 bytes.
     Be very careful of spaces in any DC directives, as a space is
the delimiter before a comment. For example, the line

          dc.b      1,2,3 ,4

will only generate 3 bytes - the ,4 will be taken as a comment.

<label>   DS.B      expression
<label>   DS.W      expression
<label)   DS.L      expression

     These  directives  will  reserve  memory  locations  and  the
contents will be initialised to zeros. If there is a label then it
will be set to the start of the area defined,  which will be on  a
word  boundary  for  DS.W  and  DS.L  directives.   There  is   no
restriction  on the size though the larger the area the longer  it
will take to save to disk.

      For example, all of these lines will reserve 8 bytes of space,
in different ways :

          ds.b 8
          ds.w 4
          ds.l 2

<label>   DCB.B     number,value
<label>   DCB.W     number,value
<label>   DCB.L     number,value

     This directive allows constant blocks of data to be generated
of the size specified,  number specifies how many times the  value
should be repeated.

FAIL
     This directive will produce the error user error.  It can  be
used  for  such things as warning the programmer if  an  incorrect
number of parameters have been passed to a macro.

OUTPUT    filename
     This directive sets the normal output filename though can  be
overridden by specifying a filename at the start of  assembly.  If
filename starts with a period then it is used as an extension  and
the output name is built up as described previously.

__G2      (reserved symbol)
     This is a reserved symbol that can be used to detect  whether
GenST is being used to assemble a file using the IFD  conditional.
The  value of this symbol depends on the version of the  assembler
and is always absolute.

REPEAT LOOPS
     It  is  often  useful  to  be able  to  repeat  one  or  more
instructions  a  particular number of times and  the  repeat  loop
construct allows this.

<label>   REPT      expression
          ENDR

     Lines to be repeated should be enclosed within REPT and  ENDR
directives  and will be repeated the number of times specified  in
the expression. If the expression is zero or negative then no code
will be generated.  It is not possible to nest repeat  loops.  For
example

          REPT      512/4             copy a sector quickly
          move.l    (a0)+,(a1)+
          ENDR

     NOTE: Program  labels should not be define within repeat  loops
to prevent label defined twice errors.

LISTING CONTROL

LIST
     This  will  turn the assembly listing on during  pass  2,  to
whatever  device was selected at the start of the assembly (or  to
the  screen of None was initially chosen).  All  subsequent  lines
will be listed until an END directive is reached,  the end of  the
text is reached, or a Nolist directive is encountered.
     Greater  control  over  listing sections of  program  can  be
achieved using LIST+ or LIST- directives. A counter is maintained,
the state of which dictates whether listing is on or off.  A LIST+
directive  adds one to the counter and a LIST- subtracts  one.  If
the  counter  is zero or positive then listing is  on,  if  it  is
negative  then listing is off.  The default starting value  is  -1
(i.e.  listing  off)  unless  a  listing  is  specified  when  the
assembler was invoked,  when it is set to zero. This system allows
a  considerable  degree of control over listing  particularly  for
include  files.  The normal LIST directive sets the counter to  0,
NOLIST sets it to -1.

NOLIST
     This will turn off any listing during pass 2.

     When  a listing is requested onto a printer or to  disk,  the
output is formatted into pages,  with a header at the top of every
page.  The header itself consists of a line containing the program
title, date, time and page number, then a line showing the program
title,  then a line showing the sub-title,  then a blank line. The
date  format  will be printed in the  form  DD/MM/YY,  unless  the
assembler  is  running  on a US Atari ST,  then  it  is  MM/DD/YY.
Between  pages  a  form-feed character (ASCII  FF,  value  12)  is
issued.

PLEN      expression
     This  will  set the page length of the assembly  listing  and
defaults to 60. The expression must be between 12 and 255.

LLEN      expression
     This  will  set the line width of the  assembly  listing  and
defaults  to 132.  The value of the expression must be between  38
and 255.

TTL       string
     This  will set the title printed at the top of each  page  to
the  given string,  which may be enclosed in  single  quotes.  The
first TTL directive will set the title of the first printed  page.
If  no  title is specified the current include file name  will  be
used.

SUBTTL    string
     Sets  the  subtitle printed at the top of each  page  to  the
given string,  which may be enclosed in single quotes.  The  first
such directive will set the sub-title of the first printed page.

SPC       expression
     This  will  output  the number of blank lines  given  in  the
expression in the assembly listing, if active.

PAGE
     Causes a new page in the listing to be started.

LISTCHAR  expression<,expression> ...
     This will send the characters specified to the listing device
(except  the  screen)  and is intended for doing  things  such  as
setting  condensed mode on printers.  For example,  on Epsons  and
compatibles the line

          listchar  15

will set the printer to 132-column mode.

FORMAT    parameter<,parameter> ...
     This allows exact control over the listed format of a line of
source  code.  Each parameter controls a field in the listing  and
must consist of a digit from 0 to 2 inclusive followed by a +  (to
enable the field) or a - (to disable it):

0    line number, in decimal
1    section name/number and program counter
2    hex data words, up to 10 words unless printer is less than 80
     characters wide, when up to three words are listed.

LABEL DIRECTIVES

label     EQU       expression

     This directive will set the value and type of the given label
to  the  results of the expression.  It may  not  include  forward
references,  or  external  labels.  If there is any error  in  the
expression,  the  assignment  will  not  be  made.  The  label  is
compulsory and must not be a local label.

label     =         expression

Alternate form of EQU statement

label     EQUR      register

     This  directive  allows  a data or  address  register  to  be
referred  to  by  a  user-name,  supplied as  the  label  to  this
directive.  This is known as a register equate.  A register equate
must be defined before it is used.

label     SET       expression

     This is similar to EQU,  but the assignment is only temporary
and  can  be  changed with a  subsequent  SET  directive.  Forward
references  cannot  be used in the expression.  It  is  especially
useful for counters within macros, for example, using a line

zcount    set       zcount+1

(assuming zcount is set to 0 at the start of the source).  At  the
start of pass 2 all SET labels are made undefined, so their values
will always be the same on both passes

label     REG       register-list

     This  allows  a symbol to be used to denote a  register  list
within MOVEM instructions,  reducing the likelihood of having  the
list at the start of a routine different from the list at the  end
of the routine. A label defined with REG can only be used in MOVEM
instructions.

<label>   RS.B      expression
<label>   RS.W      expression
<label>   RS.L      expression

     These  directives  let you set up lists of  constant  labels,
which is very useful for data structures and global variables  and
is best illustrated by a couple of examples
     Let's  assume you have a data structure which consists  of  a
long word,  a byte and another long word,  in that order.  To make
your code more readable and easier to update should the  structure
change, you could use lines such as:

          rsreset
d_next    rs.l      1
d_flag    rs.b      1
d_where   rs.l      1

and then you could access them with lines like

          move.l    d_next(a0),a1
          move.l    d_where(a0),a2
          tst.b     d_flag(a0)

As  another  example  let's assume you are  referencing  all  your
variables  off register A6 (as done in GenAM and MonAM) you  could
define them with lines such as

onstate   rs.b      1
start     rs.l      1
end       rs.l      1

you then could reference them with lines such as

          move.b    onstate(a6),d1
          move.l    start(a6),d0
          cmp.l     end(a6),d0

     Each such directive uses its own internal counter, which is reset
to 0 at the beginning of each pass. Every time the assembler comes
across  the directive it sets the label according to  the  current
value  (with word alignment if it is .W or .L) then increments  it
according to the size and magnitude of the directive. If the above
definitions  were  the first RS directives,  onstate would  be  0,
start would be 2 and end would be 6.

RSRESET
     This directive will reset the internal counter as used by the RS
directive.

RSSET     expression
     This allows the RS counter to be set to a particular value.

__RS      (reserved symbol)
     This is a reserved symbol having the current value of the RS
counter.

CONDITIONAL ASSEMBLY
     Conditional  assembly  allows  the  programmer  to  write   a
comprehensive  source  program  that can  cover  many  conditions.
Assembly  conditionals  may  be  specified  through  the  use   of
arguments,  in the case of macros,  and through the definition  of
symbols  in EQU or SET directives.  Variations in these  can  then
cause  assembly  of only those parts necessary for  the  specified
conditions.
     There   are  a  wide  range  of  directives  concerned   with
conditional assembly. At the start of the conditional blocks there
must  be  one of many IF directives and at the end of  each  block
there must be an ENDC directive.  Conditional blocks may be nested
up to 65535 levels.
     Labels  should not be placed on IF or ENDC directives as  the
directives will be ignored by the assembler.

          IFEQ      expression
          IFNE      expression
          IFGT      expression
          IFGE      expression
          IFLT      expression
          IFLE      expression

     These directives will evaluate the expression, compare it with
zero and then turn the conditional assembly on or off depending on
the  result.  The  conditions  correspond  exactly  to  the  68000
condition codes.  For example, if the label DEBUG had the value 1,
then with the following code,

          IFEQ DEBUG
logon     dc.b      'enter a command:'.0
          ENDC
          IFNE DEBUG
          opt       d+        labels please
logon     dc.b      'Yeah, gimme man:',0
          ENDC

the first conditional would turn assembly off as 1 is not EQ to 0,
while the second conditional would turn it on as 1 is NE to 0.

     NOTE: IFNE corresponds to IF in assemblers with only one
conditional directive.
     The  expressions  used in these conditional  statements  must
evaluate correctly.

IFD       label
IFND      label
     These  directives  allow  conditional  control  depending  on
whether a label is defined or not.  With IFD, assembly is switched
on if the label is defined, whereas with IFND assembly is switched
on  if the label is not defined.  These directives should be  used
with  care otherwise different object codes could be generated  on
pass  1 and pass 2 which will produce incorrect code and  generate
phasing errors. Both directives also work on reserved symbols.

IFC       'string1','string2'
     This  directive will compare two strings,  each of which  must
be surrounded  by single quotes.  If they are identical  assembly  is
switched  on,  else  it i switched off.  The  comparison  is  case
sensitive.

IFNC      'string1','string2'
     This directive is similar to the above, but only switches
assembly on  if  the strings are not identical.  This may at  first
appear somewhat useless, but when one or both of the parameters are
macro parameters it can b every useful, as shown in the next section.

ELSEIF
     This  directive toggles conditional assembly from on  to  off,
or vice versa.

ENDC
     This  directive  will terminate the current level  of
conditional assembly.  If  there  are more IF's then ENDC's an error
will be reported at the end of assembly.

IIF       expression   instruction
This  is  a  short form of the IFNE directive  allowing  a  single
instruction  or directive to be assembled conditionally.  No  ENDC
should be used with IIF directives.

MACRO OPERATIONS
     GenAM fully supports Motorola-style macros, which together with
conditional  assembly  allows you greatly  to  simplify  assembly-
language programming and the readability of your code.
     A macro is a way for a programmer to specify a whole sequence
of  instructions  or  directives  that  are  used  together   very
frequently. A macro is first defined, then its name can be used in
a macro call like a directive with up to 36 parameters.

label     MACRO
     This starts a macro definition and causes GenAM to copy all
following  lines  to  a macro buffer until an  ENDM  directive  is
encountered. Macro definitions may not be nested.

ENDM
     This terminates the storing of a macro definition, after a  MACRO
directive.

MEXIT
     This stops prematurely the current macro expansion and is best
illustrated by the INC example given later.

NARG      (reserved label)
     This is not a directive but a reserved symbol, Its value is  the
number  of parameters passed to the current macro,  or 0  if  used
when not within any macro.  If GenAM is in the case sensitive mode
then the name should be all upper-case.

MACRO PARIMETERS
     Once a macro has been defined with the Macro directive it can
be invoked by using its name as a directive,  followed by upto  36
parameters.  In the macro itself the parameters may be referred to
by  using a backslash character (\) followed by  an  alpha-numeric
(1-9,  A-Z  or  a-z)  which will be  replaced  with  the  relevant
parameter when expanded or with nothing if no parameter was given.
There  is  also the special macro parameter \0 which is  the  size
appended to the macro call and defaults to W if none is given.  If
a  macro  parameter  is  to include  spaces  or  commas  then  the
parameter should be enclosed in between < and > symbols;  in  this
case  a  >  symbol  may  be  included  within  the  parameters  by
specifying >>.
     A special form of macro expansion allows the conversion of  a
symbol to a decimal or hexadecimal sequence of digits,  using  the
syntax \<symbol> or \$<symbol>, the latter denoting hex expansion.
The symbol mast be defined and absolute at the time of expansion.
     The  parameter \@ can be useful for generating unique  labels
with each macro call and is replaced when the macro is expanded by
the  sequence  _nnn where nnn is a number which increases  by  one
with  every  macro call.  It may be expanded up to  5  digits  for
very large assemblies.
     A true \ may be included in a macro definition by specifying \\.

     A  macro  call  may  be  spread  over  more  than  one  line,
particularly  useful for macros with large numbers of  parameters.
This  can  be  done  by ending a macro  call  with  a  comma  then
starting  the next line with an & followed by tabs or spaces  then
the continuation of the parameters.
     In the assembly listing the default is to show just the macro
call and not the code produced by it. However, macro expansion
listings can  be  switched on and off using the OPT M  directive
described previously.
     Macro  calls may be nested as deeply as memory  permits,
allowing recursion if required.
     Macro  names are stored in a separate symbol table to normal
symbols so will not clash with similarly named routines,  and  may
start with a period.

MACRO EXAMPLES

EXAMPLE 1 - CALLING A LIBRARY
     As the first example, a common way of calling an Amiga library
routine is:

        save register a6
        load a6 from a library pointer
        do a jsr with offset
        restore a6

     A macro to follow the above specifications could be:

call_lib MACRO
         move.l   a6,-(sp)
         move.l   \2,a6       get lib pointer
         jsr      _LVO\l(a6)  call it
         move.l   (sp)+,a6    restore
         ENDM

     The directives are in capitals only to make them stand  out:  they
don't have to be.  If you wanted to call this macro to use the DOS
function Output the code would be:

call_lib Output,_DOSbase

     When this macro call is expanded, \1 is replaced with Output and
\2 is replaced with _DOSbase. \0, if it occurred in the macro, would
be W as no size  is given on the call.  So the above call would be
assembled as:

        move.l  a6,-(sp)
        move.l  _DOSbase,a6     get lib pointer
        jsr     _LVOOutput(a6)  call it
        move.l  (sp)+,a6        restore a6

EXAMPLE 2 - AN INC INSTRUCTION
     The 68000 does not have the INC instruction like other
processors but the same effect can be achieved using an ADDQ #1
instruction. A macro may be used to do this, like so:

inc       MACRO
          IFC       '','\1'
          fail      missing parameter!
          MEXIT
          ENDC
          addq.\0   #1,\1
          ENDM

An example call would be

          inc.1     a0

which would expand to

          addq.1    #1,a0

     The macro starts by comparing the first parameter with an empty
string and causing an error message to be issued using FAIL if  it
is equal.  The MEXIT directive is used to leave the macro  without
expanding the rest of it.  Assuming there is a non-null parameter,
the next line does the ADDQ instruction, using the \0 parameter to
get the correct size.

EXAMPLE 3 - A FACTORIAL MACRO
     Although  unlikely actually to be used as it stands, this macro
defines  a  label to be the factorial of a number.  It  shows  how
recursion  can work in macros.  Before showing the  macro,  it  is
useful to examine how the same thing would be done in a high level
language such as Pascal.

function  factor(n:integer):integer;
begin
          if n>0 then
                    factor:=n*factor(n-1)
          else
                    factor:=1
end;

     The macro definition for this uses the SET directive to do the
multiplication n*(n-1)*(n-2) etc. in this way

*    parameter 1= label,   parameter 2= 'n'
factor    MACRO
          IFND      \1
\1        set       1         set if not yet defined
          ENDC
          IFGT      \2
          factor    \1,\2-1   work out next level down
\1        set       \1*(\2)   n = n * factor(n-1)
          ENDC
          ENDM
*    a sample call
          factor test,3

     The net result of the previous code is to set test to 3! (3
factorial). The reason the second set  has (\2) instead of just \2
is  that  the  parameter  will  not  normally  be  just  a  simple
expression,  but a list of numbers separated by minus signs, so it
could assemble to:

test      set       test*5-1-1-1

(i.e. test*5-3) instead of the correct

test      set       test*(5-1-1-1)

(i.e. test *2)

EXAMPLE 4 - CONDITIONAL RETURN INSTRUCTION
     The 68000 lacks the conditional return instruction found on other
processors,  but macros can be defined to implement them using the
\@ parameter. For example, a return if EQ macro could look like:

rtseq     MACRO
          bne.s     \@
          rts
\@
          ENDM

      The \@ parameter has been used to generate a unique label every
time  the macro is called,  so will generate in this  case  labels
such as _002 and _017.

EXAMPLE 5 - NUMERIC SUBSTITUTION
     Suppose you have a constant containing the version number of
your program and wish it to appear as ASCII in a message:

showname  MACRO
          dc.b      \1,'\<version>',0
          ENDM
          .
          .
version   equ       42
          showname  <'Real Ale Search Program v'>

will expand to the line

          dc.b      'Real Ale Search Program v','42',0

Note  the  way  the string parameter is enclosed in  <  >s  as  it
contains spaces.

EXAMPLE 6 - COMPLEX MACRO CALL
     Suppose your program needs a complicated table structure which
can have a varying number of fields.  A macro can only be written  to
using those parameters that are specified,  for example:

table_entry         macro
          dc.b      .end\0-*            length byte
          dc.b      \1                  always
          IFNC      '\2',''
          dc,w      \2,\3               2nd and 3rd together
          ENDC
          dc.l      \4,\5,\6,\7
          IFNC      '\8',''
          dc.b      '\8'                text
          ENDC
          dc.b      \9
.end\@    dc.b      0
          ENDM

* a sample call
          table_entry                   &42,,,t1,t2,t3,t4,
&                                       <Enter Name:>,%0110

NOTE: THE NEXT 2 PAGES ARE MISSING FROM MY PHOTOCOPY (THANX REB!) SO
I'LL HAVE TO IMPROVISE.. I'LL MARK WHERE IT'S BACK FROM THE MANUAL.

     This is a non-trivial example of how macros can make a
programmer's  life so much easier when dealing with  complex  data
structures.  In  this  case the table consists of a  length  byte,
calculated in the macro using \@,  two optional words, four longs,
an optional string, a byte, then a zero byte. The code produced in
this example would be :

          dc.b      .end_001
          dc.b      $42
          dc.l      t1,t2,t3,t4
          dc,b      'Enter Name:'
          dc,b      %0110
.end_001  dc.b      0

OUTPUT FILE FORMATS
     GenAM is very flexible in terms of output file formats. These
are detailed in this section together with notes on the advantages
and  disadvantages  of each.  Certain  directives  take  different
actions, depending on what output file format is specified.

     The exact details of using each format will now be described.

EXECUTABLE FILES
     These  are  directly  executable,   for  example,  by  double
clicking  from the workbench, or from the CLI. The file may include
relocation information  and/or symbolic information.

ADVANTAGES
     true BSS sections, reduced development time.

DISADVANTAGES
     messy if more than one programmer.

GST LINKABLE FILES
     When  writing  larger programs,  or  when  writing  assembly
language  modules  for  use  from  the  high  level  language,   a
programmer needs to generate a linkable file.  The GST link format
is  supported  by  most of the high level  languages  produced  in
Britain as well as others,  for example HiSoft Basic,  Lattice  C,
Prospero  Fortran and Prospero Pascal.  GST format files  normally
have the extension .BIN.

ADVANTAGES
     Great  degree of freedom - imported labels  can  be
used  practically anywhere including within arbitrary  expressions,
libraries can be created from the assembler,  import methods means
the assembler can detect type conflicts.

DISADVANTAGES
     Library format means selective library linking  can
be  slow,  true AmigaDOS sections not supported as standard.

CHOOSING THE RIGHT FILE FORMAT
     If  you wish to link with a high level language  there  isn't
usually  much  choice  -  you have  to  use  whichever  format  is
supported by the language.
     If  you  are writing entirely in assembly language  then  the
normal  choice has to be executable - it is fast to  assemble,  no
linking  required,  and  allows assembly to memory  for  decreased
development time.
     If  you  are writing a larger program,  say bigger  than  32k
object,  or writing a program as a team,  then linkable code often
makes  most sense.  We recommend GST-linkable over DRI because  of
the much greater flexibility of the format.

OUTPUT FILE DIRECTIVES
     This section details those directives whose actions depend on
the  output  file format chosen.  The file format  itself  can  be
chosen by one of the following methods; command line options using
GENST2.TTP;  clicking on the radio buttons in the Assembly Options
dialogue box from the editor,  or with the OPT L directive at  the
beginning of the source file.

Icons are used to denote those sections specific to a file format,
viz

*EXEC*    Executable-code, also assembled to memory code.

*GST*     GST-linkable code

*DRI*     DRI-linkable code.

BACK TO THE MANUAL, HOPE I GOT IT RIGHT, shit! THE NEXT BIT IS VERY
DIFFERANT SO THE ABOVE IS PROBABLY WRONG!           PARASITE 4.26am

SECTIONS

SECTION string<,type>
     This  defines a switch to the named section and optionally
defines it's type. A program may consist of several sections which
will be concentrated together with other sections of the same name in
the final executable file. This will use the supplied string and type
as the section name and type of this section (of hunk) respectivly.
Each can be up to 32 characters long and should not include tabs or
spaces or be enclosed in quotes. The casing of the name is
significant. You may have many SECTION directives in your program.
     The type can be one of the following (in upper or lower case):

CODE    code section, public memory
CODE_F  code section, Fast memory
CODE_C  code section, chip memory
DATA    data section, public memory
DATA_F  data section, fast memory
DATA_C  data section, chip memory
BSS     BSS section, public memory
BSS_F   BSS section, fast memory
BSS_C   BSS section, chip memory

     CODE sections are used for executable instructions, DATA sections
for initialised data (constants), and BSS for un-initialised data. BSS
sections  have the advantage that they take no disk space - only the
length of the BSS section is stored. If you define a section to be BSS
you can only use the directive to produce code - any other code
generating instructions will cause a binary file i/o error.
     NOTE: Do not use types requesting chip or fast memory, with
versions prior to version 2.3 of the Alink linker - these versions
will crash!

CODE/DATA/BSS
     These directives are supported for compatability with the Amiga
macro assembler. They are the same as specifying the directive as the
section name and type.

IDNT string
     This will use the supplied name as the hunk unit name for this
section, It can be up to 32 characters long and should not include
tabs or spaces or be enclosed in quotes.

IMPORTS AND EXPORTS
     With both linkable types of program it is crucial to be  able
to import and export symbols,  both relative symbols (i.e. program
references) and absolute symbols (i.e.  constants). The AmigaDOS
linker format does not distinguish between these types; however by
specifying the type when importing, the assembler can type check,
often  finding programming errors that would otherwise be missed.

XDEF      export<,export>...
     This  defines  labels  for  export  to  other  programs   (or
modules).  If any of the labels specified are not defined an error
will occur. It is not possible to export local labels.

EXEC
     This directive is ignored

XREF      import<,import>...
XREF.L    import<,import>...
     This  defines  labels to be imported from other  programs  or
modules.  If any of the labels specified are defined an error will
occur.  The  normal  XREF  statement should be used  to  import  a
relative label (i.e.  program reference),  while XREF.L should  be
used to import absolute labels (i.e. constants). If you do not type
your imports you should turn type-checking off using OPT T-
     Importing a label more than once will not produce an error.

EXEC
     This directive is ignored

USING IMPORTS IN EXPRESSIONS

EXEC
     There are no imports! However referances to labels in other
sections are subject to the limitations described below.

LINK
     Imports  may be used in expressions but only one  import
per  expression is allowed.  The results of an expression with  an
import  in must be of the form import+number  or  import-number.
Imports can be combined with arbitrarily complex  expressions,  so
long as the complex expression lexically precedes it, for example

          move.l    3+(1<<count+5)+import

EXPRESSION     GST            DRI       EXAMPLE
byte           Y              N         move.b #test,do
word           Y              Y         move.w test(a3),d0
long           Y              Y         move.l test,d0

COMMENT   comment string

This directive is ignored at present

ORG       expression
     This will make the assembler generate position dependant code
and  set  the program counter to the given  value.  Normal AmigaDOS
program,s do not need an ORG statement even if position dependant.
It  is included to allow code to be generated for the ROM port  or
for other 68000 machines.  More than one ORG statement is  allowed
in a source file but no padding of the file is done.

EXEC
     It  should  be used with great care as the  binary  file
generated will probably not execute correctly when double clicked.
as  no  relocation information is written  out.  The  binary  file
produced  has  the standard AmigaDOS header at  the  front,  but  no
relocation information.

LINK
     This directive is not allowed.

OFFSET    <expression>
     This  switches  code  generation  to  a  special  section  to
generate absolute labels. The optional expression sets the program
counter for the start of this section. No bytes are written to the
disk and the only code generating directive allowed is DS.  Labels
defined in this section will be absolute.  For example,  to define
some of the system variables of the ST. (This is in the AMIGA
manual!);

          offset    $400
etv_timer           ds.l      1         will be $400
etv_critic          ds.l      1         404
etv_term            ds.l      1         408
ext_extra           ds.l      5         40C
memvalid            ds.l      1         420
memcntlr            ds.w      1         424

__LK      (reserved symbol)
     This  is a reserved symbol that can be used to  detect  which
output  mode  is specified.  The value of this symbol  is  alwayus
absolute and one of the following:

3 linkable
4 executable

      Values 0-2 are reserved for the production of ST code; other
values and the high word are reserved for future expansion.

RETURN CODES
     When using the stand alone assembler from within batch files or
make files, it's return code can be used to determine  the success of
the assembly. Values returned are:

100+ initialisation failure
 20  fatal error
  5  warnings
  0  OK

DIRECTIVE SUMMARY

ASSEMBLY CONTROL
END       terminate source code
INCLUDE   read source file from disk
INCBIN    read binary file from disk
OPT       option control
EVEN      ensure PC even
CNOP      align PC arbitrarily
DC        define constant
DS        define space
DCB       define constant block
FAIL      force assembly error

REPEAT LOOPS
REPT      start repeat block
ENDR      end repeat block

LISTING CONTROL
LIST      enable list
NOLIST    disable list
PLEN      set page length
LLEN      set line length
TTL       set title
SUBTTL    set sub-title
PAGE      start new page
LISTCHAR  send control character
FORMAT    define listing format

LABEL DIRECTIVES
EQU       define label value
EQUR      define register equate
SET       define label value temporarily
REG       define register list
RS        reserve space
RSRESET   reset RS counter
RSSET     set RS counter

CONDITIONAL ASSEMBLY
IFEQ      assemble if zero
IFNE      assemble in non-zero
IFGT      assemble if greater than
IFGE      assemble if greater than or equal to
IFLT      assemble if less than
IFLE      assemble if less than or equal to
IFD       assemble if label defined
IFND      assemble if label not defined
IFC       assemble if strings same
IFNC      assemble if strings different
ELSEIF    switch assembly state
IIFC      immediate IF

MACROS
MACRO     define macro
ENDM      end macro definition

OUTPUT FILE DIRECTIVES
MODULE    start new module
SECTION   switch section
XDEF      define label for export
XREF      define label for import
COMMENT   send linker comment
ORG       set absolute code generation
OFFSET    define offset table

RESERVED SYMBOLS
NARG      number of macro parameters
__G2      internal version number
__RS      RS counter
__LK      output file type

BLINK LINKER
     This version of BLINK is a public domain limker designed as a
replacement for the standard AmigaDOS linker, Alink. The program has
many powerful features, but in the simplest case the command line is

blink (from) <infile.o> [<infile2.o>...] [ TO <outfile>]

which specifies one or more input files and an output file. Normally
all sections will be placed in seperate hunks, but they can be forced
into one hunk by specifying SMALLCODE or SMALLDATA on the command
line. For example;

blink test.o

will link test.o into the file test

blink FROM start.o middle.o end.o TO total

will link the specified three files into total

blink FROM start.o middle.o end.o TO total SMALLCODE

as above but coalescing for BLink are contained in a  file on disk 2,
which can be read on screen or printed out in the usual manor.



CHAPTER 4: SYMBOLIC DEBUGGER

INTRODUCTION
     Programs written in assembly language are particularly error-
prone  because  even a slight mistake can result  in  the  entire
machine crashing.  There are various forms of bugs,  ranging from
the trivial (e.g.  a missing CR in a printout),  though the usual
(e.g.  an incorrect result_ to the very serious (e.g. the machine
completely hanging, perhaps with a weird display).
     To help you find and correct all forms of bugs, Devpac includes
MonAm.  MonST is a symbolic debugger and disassembler which  lets
you examine programs and memory,  execute programs an instruction
at  a  time and trap processor exceptions  caused  by  programmer
error. As MonAm is symbolic you can look at your program complete
with all the original labels,  making debugging very much  easier
than having to battle with 6-digit hex numbers (or 8 digits on the
68020!).
     Although MonAm is a low-level debugger, displaying such things as
68000 instructions and bytes of memory,  it can also be used  for
debugging  programs  written  with any  compiler  that  generates
machine-code output.  If the compiler has the option to dump  the
symbols into the binary code then you will see your procedure and
function  names  within  the code,  and you can  even  view  your
original  source  code.
     As MonAm uses its own screen (in the Amiga sense), if you are
debugging a program with windows your program will not be sent re-draw
messages whilst you are using the debugger. Many other Amiga debuggers
do send these messages - it can be very confusing.

EXCEPTIONS
     MonAm uses the 68000 processor exceptions to stop runaway
programs and to single-step,  so at this point it would be useful
to  explain them and what normally happens when they occur on  an
Amiga.
     There are various types of exception that can  occur,  some
deliberately,  others  accidentally.  When  one  does  occur  the
processor saves some information on the SSP, goes into Supervisor
mode and jumps to an exception handler. On the Amiga these normally
produce a software error tash held system requester, or the dreaded
guru, but when MonAM is active it re-directs  some of these exceptions
so it can take control  when they occur. The various forms of
exceptions, their usual results, and  what happens when they occur
with MonAm active is  shown  in the following table:

  No.   EXCEPTION              MONAM ACTIVE
   2    bus error              trapped
   3    address error          trapped
   4    illegal instruction    trapped
   5    zero divide            trapped
   6    CHK instruction        trapped
   7    TRAPV instruction      trapped
   8    privilege violation    trapped
   9    trace                  single stepping
  10    line 1010 emulator     trapped
  11    line 1111 emulator     trapped
  32    trap #0 to #15         trapped

    The exact causes of the above exceptions (and how best to recover
from  them)  are  detailed at the end of  this  section,  but  to
summarise:

Exceptions  2  to  8 are caused by a  programmer  error  and  are
trapped by MonAM. Exception  9  can remotely be caused by programmer
error  and  is used by MonAM for single stepping. The  rest  (i.e.
Trap instructions) are  diverted  into MonAm,  but  can  subsequently
be re-defined to be  exploited  by programs if required.
      Occasionally  very  nasty crashes can cause the whole  screen
to fill with colourful garbage, which looks very  impressive,  but
is not very useful!

INVOKING MONAM
     Monam is invoked by typing the command

monam2 (RETURN)

     This can optionally be followed by a program name, and a command
line to be passed to it. For example:

monam2 c:genam2 examples/demo.s (RETURN)

will cause Monam to be invoked, to in turn load genam, and pass a
filename to it.
     When Monam has loaded, the screen will display three windows in
which all Monam information is displayed. Immidiatly after loading the
prompt enter program name or press return: will appear. At this point
you have to choose weather you are going to debug a particular
program, or just have a look around memory.

DEBUGGING A PROGRAM
     If you wish to debug a specific program, you should enter it's
filename including drive and directory if required and Manam will try
and load the program. If it fails, it will display:

AmigaDOS error xxx

and you can use the (CTRL)-L command to try again.
     Assuming the filename is valid, monam will load it. it will also
check for any symbols within a file. After a succesful load, the
prompt enter command line: will appear and you may type in a command
line thet will be passed to the program being debugged in the standard
way. If you don't want a command line, press return alone. The message

Exception:Breakpoint

will appear together with the front panel display. It says Breakpoint
because Monam places a breakpoint at the first instruction of the
program then executes it.

MONAM & MULTI-TASKING
     the Amiga is a multi-tasking machine, and this imposes some
restrictions on what monam can do. Having loaded a program (or task)
into it, that task is suspended. This means it is waiting, in this
case for a Monam command to let it continue. The other state the task
can be in is executing - that is it is running at the same time. Some
commands require one of these states to operate - for example you can
only single-step a task that is suspended. if it is running you will
get the error 'Task must be suspended!' when you try.

EXAMINING MEMORY
    If you are just interested in looking at memory, press (RETURN)
and you will see the front panel display, and get the command:

prompt.

SYMBOLIC DEBUGGING
     A major feature of MonAm is its ability to use symbols taken from
the original program whilst debugging. MonAm uses standard AmigaDOS
file SYMBOL hunks as produced by most Amiga programs that produce
executable files, such as linkers, compilers and GenAm.

MONAM DIALOGUE AND ALERT BOXES
     MonAm makes extensive use of dialogue and alert-boxes which
are similar in concept to those in intuition programs but have several
differances.
     A Monam dialogue box displays the prompt ESC to abort above  the
top  left  corner of the box together  with  a  prompt,  normally
followed  by a blank line with a cursor.  At any time a  dialogue
box  may be aborted by pressing Esc,  or data may be  entered  by
typing.  The cursor keys,  Backspace and Del keys may be used  to
edit  entered  text in the usual way and the whole  line  may  be
delted by pressing the (AMIGA)-X key combination.
     An entered line is terminated by pressing  the  Return
key, though if the line contains errors the screen will flash and
the  Return key will be ignored allowing correction of  the  data
before pressing Return again.
     A MonAM alert box is a small box displaying a  message  together
with the prompt (Return) and is normally used to inform the  user
of  some form of error.  The box will disappear on  pressing  the
Return or Esc keys, whichever is more convenient.

INITIAL DISPLAY
     Unless  you  have chosen the Debug option within the  editor  you
will be presented with a dialogue box prompting for an executable
program name. If you wish to debug a program from disk you should
enter the filename (which defaults to an extension of .PRG)  then
press Return,  then you will be prompted for any command line. If
you do not wish to debug a program from disk at this  stage,  for
example  you  wish to investigate memory,  press the Esc  key  or
enter a blank filename.

FRONT PANEL DISPLAY
     The main display of MonAm is via a Front Panel showing registers,
memory and instructions. The name Front Panel stems from the type
of  panels that were mounted on mainframe and mini  computers  to
provide  information on the state of the machine at a  particular
moment,  usually through the use of flashing lights. These lights
represent  whether  or  not  particular  flip-flops   (electronic
switches) within the computer are open or closed;  the flip-flops
that are chosen to be shown on this panel are normally those that
make  up  the internal registers and flags of the  computer  thus
enabling  programmers and engineers to observe what the  computer
is doing when running a program.
     So these are hardware front panel displays; what MonAM provides
you with is a software front panel - the code within MonAm works
out the state of your computer and then displays this information
on the screen.

The initial MonAm display consists of three windows:

     The top window (number 1) displays the values of the data and
address registers, together with the memory pointed to by these
registers.
     The next  window  (number 2)  is the  disassembly  window  which
displays several lines of instructions,  by default based  around
the program counter (PC),  shown in the title area of the window.
A => sign is used to denote the currant value of the PC
     Window number 3 is the memory window which displays a section  of
memory in word-aligned hex and ASCII.
     One  of  the most powerful features of MonAm is  its  flexibility
with  windows - up to 2 additional windows may  be  created,  the
font  size  can  be  changed,  and  windows  may  be  locked  to
particular registers, these features are detailed later.

SIMPLE WINDOW HANDLING
     MonAm has the concept of a current window - this is  denoted  by
displaying its title in black.  The current window may be changed
by pressing the Tab key to cycle between them, or by pressing the
(AMIGA) key together  with the window  number, for example (AMIGA)-2
selects  the disassembly window.
     NOTE: If your typing seems to be ignored in MonAm don't be
alarmed, it means that another window is active, such as your
programs. To correct this clich on any part of the MonAm display. you
can always tell when the monAm window is active because the mouse
pointer will be bug shaped.

COMMAND INPUT
     MonAm is controlled by single-key commands which creates a  very
fast user-interface,  though this can take getting used to if you
are  familiar with a line-oriented command interface  of  another
debugger. Users of HiSoft Devpac on other machines will find many
commands  are  identical,  particulary with the Spectrum  and  QL
debuggers, though the window commands are unique to MonAm. The
commands are almost identical to DEVPAC ST version 2.
     In general the (AMIGA) key - when  used  in conjunction with
other keys it it acts on the  current window.
     Commands  may  be entered in either upper or  lower  case.  Those
commands  whose  effects are potentially disastrous  require  the
Ctrl  key to be pressed in addition to a command  key.  The  keys
used  where  chosen to be easy to  remember,  wherever  possible.
Commands  take  effect immediately - there is no  need  to  press
Return  and  invalid commands are simply  ignored.  The  relevant
sections  of  the  front panel display  are  updated  after  each
command so any effects can be seen immediately.
     MonAm is a powerful and sometimes complex program and we  realise
that  it  is  unlikely  that many users  will  use  every  single
command.  For  this reason the remainder of the MonST  manual  is
divided into two sections - the former is an introduction to  the
basic  commands  of  the program,  while the  latter  is  a  full
reference section.  It is possible for new users and beginners to
use the debugger effectively while having only read the Overview;
don't be intimidated by the Reference section.

MONAM OVERVIEW
     To start with you will need to load a program to debug;  if  you
have  assembled a program to memory you can use the Debug  option
of the assembler or linker.
     The  most  common  command  in  MonAm is  probably  single-step,
obtained  by  pressing  Ctrl-Z (or Ctrl-Y if  you  find  it  more
convenient). This will execute the instruction at the PC, the one
shown in the Register window and,  normally,  also in the  Disas
sembly  window.  After executing it the debugger re-displays  the
values  of the registers and memory displayed,  so you can  watch
the processor execute your program, step by step. Single-stepping
is  the  best  way of going through sections  of  code  that  are
suspect  and  require deeper investigation,  but it is  also  the
slowest  - you may only be interested in a section of  code  near
the  end of your program which could take ages to get to  if  you
have to single-step all the way. There is, of course, an answer.
     A breakpoint is a special word placed into your program to  stop
it  running and enter MonST.  There are many types of  breakpoint
but  we  will  restrict ourselves to  the  simplest  for  now.  A
breakpoint  may  be  set by pressing (AMIGA)-B,  then  entering  the
address you wish to place the breakpoint. You can enter addresses
in MonSt in hex (the default base),  as a symbol, or as a complex
expression.  Examples of a valid address are  1A2B0,  prog_start,
10+mydata.  If  you  type in an invalid address the  screen  will
flash and allow you to correct the expression.
     Having set a breakpoint you need some way of letting your program
actually  run,  and  Ctrl-R will do this.  If will  execute  your
program  using the registers displayed and starting from the  PC.
MonST will be re-entered if a breakpoint has been hit,  or if  an
exception occurs.
     MonAm uses its own screen display which is independent from  your
own  programs.  If you press the v key you will see your  current
programs  display,  pressing  another key switches  you  back  to
MonST. This allows you to debug programs without disturbing their
output at all.
     MonAm uses its own windows to,  and any window may be zoomed  to
the  full screen size by pressing (AMIGA)-Z.  To return to  the  main
display press (AMIGA)-Z or the Esc key.  The Esc key is also the best
way of getting out of anything you may have invoked by  accident.
The Zoom command,  like all (AMIGA)- commands,  works on the  current
window  which you can change by pressing Tab.  You can  dump  the
current window to your printer by pressing (AMIGA)-P.
     To change the address from which a window  displays  its  data,
press (AMIGA)-A,   then  enter  the  new  address.   Note  that  the
disassembly  window will always re-display from the PC after  you
single-step,  because  it  is locked to the PC.  The  locking  of
windows is detailed in the Reference section.
     To quit MonAm press Ctrl-C. This returns Monam directly to the
CLI. If the task you are debugging is still running or suspended when
you try and quit, you will be warned. If Monam terminates while the
task under investigationis running, the machine will crash if any
execption occurs subsiquently. A safer way is to use the ctrl-Q
command to stop the task first. If you used the Debug option from the
editor then  Ctrl-C will always terminate MonAm as well as your
program.
      We  hope this overview has given you a good idea  of  the  most
common  features  of  MonST to let you get on  with  the  complex
process of writing and debugging assembly language programs. When
you  feel  more confident you should try and read  the  Reference
section, probably best taken, like all medicine, in small doses.

MONAM REFERENCE

NUMERIC EXPRESSIONS
     MonAm has a full expression evaluator,  based on that in  GenST,
including operator precedence.  The main differences are that the
default  base  is hexadecimal (decimal may be denoted  with  a  \
sign),  there is no concept of types of expressions (relative  or
absolute), ø  is used only for multiplication and there is a not-
equals operator, <>.
     Symbols may be referred to and are normally  case-sensitive  and
significant  to either 8 or 22 characters (depending on the  form
of debug used), though this can be changed with the MonAm Preferences
command.
     Registers  may be referred to simply by name, such as A3 or D7
(case insensitive),  but this clashes with hex numbers. To obtain
such  hex numbers precede them with either a leading zero or a  $
sign. A7 refers to the user stack pointer.
     There  are several reserved symbols which are  case  insensitive,
namely CODE, SP, SR, and SSP. SP refers to either  the user- or
supervisor-stack, depending on the current value of the status
register. CODE refers to the first in the program. This is the same as
HUNK1. The second hunk is HUNK2 and so on.
     In addition there are 10 memories numbered M0 through  M9,  which
are treated in a similar way to registers and can be assigned  to
using  the Register Set command.  Memories 2 through 5  inclusive
refer  to  the current start address of the relevant  window  and
assigning to them will change the start address of that window.
     The MonAm expression evaluator also supports  indirection  using
the { and } symbols.  Indirection may be performed on a byte word
or long basis, by following the } with a period then the required
size,  which defaults to long.  If the pointer is invalid, either
because the memory is unreadable or even (if the word or longword
indirection is used) then the expression will not be valid.

For example, the expression:

       (data_start+10).w

will return the word contents of location data_start+10, assuming
data_start is even. Indirection may be nested in a similar way to
ordinary parenthesis.

WINDOW TYPES
     There  are  four  window types and the exact  contents  of  these
windows and how they are displayed is detailed below. The allowed
types of windows is shown in the table below.

Window  Allowed Types
  1     Register
  2     Disassembly
  3     Memory
  4     Disassembly, Memory or Source-code
  5     Memory

REGISTER WINDOW DISPLAY
     The  data  registers are shown in hex,  together with  the  ASCII
display  of  their low byte and then a hex display of  the  eight
bytes  they point to in memory.  The address registers  are  also
shown in hex,  together with a hex display of 12 bytes.  As  with
all hex displays in MonAm this is word-aligned, with non-readable
memory displayed as **.
     The status  register  is  shown  in  hex  and  in  flag   form,
additionally with U or S denoting user- or supervisor-modes.  A7'
denotes the supervisor stack pointer,  displayed in a similar way
to the other address registers.
     The PC value is shown together with a disassembly of the  current
instruction.  Where this involves one or more effective addresses
these are shown in hex, together with a suitably-sized display of
the memory they point to.

For example, the display

   TST.W $12A(A3)  ;00001FAE 0F01

signifies that the value of $12A plus register A3 is  $1FAE,  and
that the word memory pointed to by this is $0F01.  A more complex
example is the display

        MOVE.W $12A(A3),-(SP) ;00001FAE 0F01 =>002AC08 FFFF

     The source  addressing  mode is as before  but  the  destination
address  is $2AC08,  presently containing $FFFF.  Note that  this
display is always of a suitable size (MOVEM data being  displayed
as a quad-word) and when pre-decrement addressing is used this is
included in the address calculations.

DISASSEMBLY WINDOW DISPLAY
     Disassembly  windows display memory as disassembled  instructions
to the standard described below.  On the left the hex address  is
shown,  followed by any symbol,  then the disassembly itself. The
current value of the PC is denoted with >.
     If the instruction has a breakpoint placed on it this  is  shown
using  square brackets ([ ]) afterwards,  the contents  of  which
depend on the type of breakpoint.  For stop breakpoints this will
be the number of times left for this instruction to execute,  for
conditional  breakpoints  this  will  be  a  ?  followed  by  the
beginning  of the conditional expression,  for count  breakpoints
this  will  be a = sign followed by the current  count,  and  for
permanent breakpoints a symbol resembling a small zero in
superscript is shown.
     The exact format  of  the  disassembled  op-codes  is  Motorola
standard,  as  GenAM accepts.  All output is  upper-case  (except
lower-case  labels) and all numeric output is  hex,  except  Trap
numbers. Leading zeroes are suppressed and the $ hex delimiter is
not  shown on numbers less than 10.  Where relevant numerics  are
shown  signed.
     The only deviation from Motorola standard is  the
register  lists  shown in MOVEM instructions - in order  to  save
display  space  the  type of the second register in  a  range  is
abbreviated, for example:

        MOVEM.L d0-d3/a0-a2,-(sp)

will be disassembled as:

        MOVEM.L d0-3/a0-2,-(sp)

    Certain library calls will be shown symbolically even if no symbol
information was loaded with your program. The dissassembler is
intelligent and recognises a MOVE into register a6 follower by a JSR
using a6 and if it is recognised then will be displayed by name, for
example:

        MOVE.L   4,a6
        JSR      _LVOOpenLibrary(a6)

     It does this for the exec, graphics and intuition libraries,
using the special file libs:libfile.monam. if this file is not found
during Monams initialisation than such a dissassembly will not occur.

MEMORY WINDOW DISPLAY
     Memory  windows  display  memory in the form of  a  hex  address,
word-aligned hex display and ASCII.  Unreadable memory  locations
are denoted by **.  The number  of  bytes shown is calculated  from
the window width, up to a maximum of 16 bytes per line.

SOURCE-CODE WINDOW DISPLAY
     The source code window displays ASCII files in a similar way to a
screen  editor.  The default tab setting is 8 though this can  be
toggled to 4 with the Edit Window command.

WINDOW COMMANDS
    The (AMIGA) key is generally used for controlling windows,  and
when used to apply to the current window. This is denoted by having an
inverse title and can be changed by pressing the Tab or (AMIGA) plus
the window number.
     Most window commands work in any window,  zoomed or  not,  though
when  it  does  not make sense to do  something  the  command  is
ignored.

(AMIGA)-A                                             SET ADDRESS
This sets the starting address of a memory or disassembly window.

(AMIGA)-B                                          SET BREAKPOINT
Allows  the setting of any type of  breakpoint,  described  later.

(AMIGA)-E                                             EDIT WINDOW
On a memory window this lets you edit memory in hex or ASCII. Hex
editing can be accomplished using keys 1-9,  A-F,  together  with
the cursor keys. Pressing Tab switches between hex & ASCII, ASCII
editing takes each keypress and writes it to memory.  The  cursor
keys can be used to move about memory.  To leave edit mode  press
the Esc key.

On a register window this is the same as (AMIGA)-R, Register Set,
described shortly.

On a source code window this toggles the tab setting  between  4
and 8.

(AMIGA)-L                                            LOCK WINDOWS
This  allows disassembly and register windows to be locked  to  a
particular register. After any exception the start address of the
window is re-calculated, depending on the locked register.
     To  unlock simply enter a blank string. By default window 2 is
locked  to  the  PC.  You  can lock  windows  to  each  other  by
specifying a lock to a memory window, such as M2.

(AMIGA)-O                                              SHOW OTHER
This  prompts for an expression and displays it in  hex,  decimal
and as a symbol if relevant.

(AMIGA)-P                                            PRINTER DUMP
Dumps the current window onto the printer.  It can be aborted  by
pressing Esc.

(AMIGA)-R                                            REGISTER SET
Allows  any  register to be set to a  value,  by  specifying  the
register, an equals sign, then its new value. It can also be used
to set the value of memories. For example the line:

           a3=a2+4

sets  register A3 to be A2 plus 4.  You can also use this to  set
the  start address of windows when in zoom mode so that  on  exit
from  zoom  mode  the  relevant window  starts  at  the  required
address.

NOTE: Do not assign M4 if window 4 is currently  a  source-code
window.

(AMIGA)-S                                           SPLIT WINDOWS
This  either splits windows 2 into 2 and 4,  or splits  window  3
into  3 and 5.  Each new window is independent from its  creator.
Pressing (AMIGA)-S again will unsplit the window.

(AMIGA)-T                                             CHANGE TYPE
This only works on window 4 (created either by splitting window 2
or by loading a source file).  It changes the type of the  window
between disassembly,  memory and source-code (if a file has  been
loaded).

(AMIGA)-Z                                             ZOOM WINDOW
This zooms the current window to be full size. Other Alt commands
are  still available and normal size can be achieved by  pressing
Esc or (AMIGA)-Z again.

NOTE: Zooming the register windows shows the values of the memoris M0
to M9.

CURSOR KEYS
     The cursor keys can be used on the current window,  the action of
which depends on the window type.

On  a  memory  window all four cursor  keys  change  the  current
address, and Shift Up Cursor and Shift Down Cursor move a page in
either direction.

On  a  disassembly window Up Cursor and Down  Cursor  change  the
start  address  on an instruction basis,  Left Cursor  and  Right
Cursor change the address on a word basis.

On  a  source-code window Up Cursor and Down  Cursor  change  the
display on a line basis and Shift Up Cursor and Shift Down Cursor
on a page basis.

SCREEN SWITCHING
     Monam uses  its  own  screen  display and will always make itself
the front and active window whenever an exception (including
breakpoints) occurs.

V                                               VIEW OTHER SCREEN
This will put the monam screen to the back, normally showing your
prograns screen Pressing any key will return the MonAm screen (so lang
as you have not activated any other window).

BREAKPOINTS
     Breakpoints  allow you to stop the execution of your  program  at
specified points within it. MonST allows up to eight simultaneous
breakpoints,  each  of  which may be one of five  types.  When  a
breakpoint  is hit Monam is entered and then decides  whether  or
not to halt execution of your program,  entering the front  panel
display,  or continue,  this decision is based on the type of the
breakpoint and the state of your program's variables.

SIMPLE BREAKPOINTS
     These are one-off breakpoints which,  when executed,  are cleared
and cause Monam to be entered.

STOP BREAKPOINTS
     These are breakpoints that cause program execution to stop  after
a particular instruction has been executed a particular number of
times.  In  fact a simple breakpoint is really a stop  breakpoint
with a count of one.

COUNT BREAKPOINTS
     Merely counters; each time such a breakpoint is reached a counter
associated with it is incremented, and the program will resume.

PERMANENT BREAKPOINTS
     These  are  similar to simple breakpoints except  that  they  are
never  cleared  -  every  time  execution  reaches  a   permanent
breakpoint MonAm will be entered.

CONDITIONAL BREAKPOINTS
      The most powerful type of breakpoint and  these  allow  program
execution to stop at a particular address, only if an arbitrarily
complex set of conditions apply.  Each conditional breakpoint has
associated with it an expression (conforming to the rules already
described).  Every time the breakpoint is reached this expression
is evaluated,  and if it is non-zero (i.e. true) then the program
will be stopped, otherwise it will resume.

(AMIGA)-B                                          SET BREAKPOINT
This  is  a window command allowing the setting  or  clearing  of
breakpoints  at any time.  The line entered should be one of  the
following forms, depending on the type of breakpoint required:

<address>
will set a simple breakpoint.

<address>,<expression>
will  set a stop breakpoint at the given address,  after  it  has
executed <expression> times.

<address>,=
will set a count breakpoint.  The initial value of the count will
be zero.

<address>,*
will set a permanent breakpoint.

<address>,?<Expression>
will set a conditional breakpoint, using the given expression.

<address>,-
will clear any breakpoint at the given address.

     Breakpoints  cannot  be  set  on  addresses  which  are  odd   or
unreadable,  or  in  ROM.
     Every  time a breakpoint is reached,  regardless of  whether  the
program  is  interrupted  or  resumed,   the  program  state   is
remembered in the History buffer, described later.

HELP                                    SHOW HELP AND BREAKPOINTS
This displays the current breakpoints, task status, its segment list
(showing where the program is), free memory and the system memory
list. (AMIGA) commands are available within this display. For UK A500
1.2 users (who cannot use the help key) this can also be obtained by
pressing (AMIGA)-H

Ctrl-B                                             SET BREAKPOINT
Included  mainly  for compatibility with MonAm 1,  this  sets  a
simple breakpoint at the start address of the current window,  so
long  as it is a disassembly window.  If a breakpoint is  already
there then it will be cleared.

U                                                        GO UNTIL
This prompts for an address, at which a simple breakpoint will be
placed then program execution resumed.

Ctrl-K                                           KILL BREAKPOINTS
This clears all set breakpoints.

Ctrl-A                                SET BREAKPOINT THEN EXECUTE
A  command  that places a simple breakpoint  at  the  instruction
after that at the PC and resumes execution from the PC.  This  is
particularly  for DBF-type loops if you don't want to go  through
the loop, but just want to see the result after the loop is over.

Ctrl-X                                     STOP PROGRAM EXECUTING
This is a command to stop your task while it is executing. It does
this by forcing the trace bit to be set, so you will get a trace
exception. While this does work, be very careful if you stop it in th
middle of some AmigaDOS ROM routines, particually signal handling and
message passing.
     NOTE: The above command accesses memory fields that are not
guarenteed to remain the same for differant versions of the Amiga
operating system. Initially you should try it at a time when nothing
important is in the machine to check compatibility with the version of
the operating system you are using before you are forced to use it
when a task goes a little beserk. This command used to be Ctrl-S on
MonAm version 1.

HISTORY
     MonAm  has  a  history  buffer in which  the  machine  status  is
remembered for later investigation.
     The most common way of entering data into the history buffer  is
when  you single-step,  but in addition every breakpoint  reached
and  every  exception caused enters the machine  state  into  the
buffer. Various forms of the Run command also cause entries to be
made into this buffer.
     NOTE:  The  history  buffer has room for five entries -  when  it
fills  the  oldest entry is removed to make room for  the  newest
entry.

H                                             SHOW HISTORY BUFFER
This opens a large window displaying the contents of the  history
buffer. All register values are shown including the PC as well as
a disassembly of the next instruction to be executed.
     NOTE: If a  disassembly  in the  History  display  includes  an
instruction  which has a breakpoint placed on the [ ]s will  show
the  current values for that breakpoint,  not the values  at  the
time of the entry into the history buffer.

QUITTING MONAM

Ctrl-C                                                  TERMINATE
This returns Monam directly to the CLi or to the editor if you invoked
Monam from the editor. If the task you are debuggingis still running
or suspended when you try and quit, you will be warned. If monam
terminates while the task under investigation is running, the machine
will crash if any exception occurs subsiquently. A safer way is to use
the Ctrl-Q command to stop the task first.
     If the Debug option has been used from the  GenAm editor  then
MonAm will  terminate  automatically  when  the  program  it  is
debugging has terminated.

CTRL-Q                                             QUIT A PROGRAM
This is a way of forcing a task being debugged to Quit. This can be
hazardous to use, and should only be done as a last resort. if your
program is terminated in this way it will not clean up, and thus not
de-allocate any memory it was using or close windows etc.

     NOTE: The above command accesses memory fields that are not
guaranteed to remain the same for differant versions of the operating
system. Initially you should try it at a time when nothing important
is in th machine to check compatability with the version of the
operating system you are using before you are forced to use it when a
task goes a little beserk.

LOADING & SAVING

Ctrl-L                                    LOAD EXECUTABLE PROGRAM
This  will prompt for an executable filename then a command  line
and will attempt to load the file ready for execution.  If  MonAm
has  already loaded a program it is not possible to load  another
until the former has terminated.
     The file to be loaded must be an executable file. use the load
binary file command if you wish to edit other file types.
     NOTE: This command in not available if Monam has been invoked
using Debug from the editor.

B                                                LOAD BINARY FILE
This  will  prompt  for  a filename  and  optional  load  address
(separated  by  a  comma)  and will  then  load  the  file  where
specified.  If  no  load  address is given then  memory  will  be
allocated  from  the system and used.  M0 will be set  to  the  start
address and M1 to the end address.

S                                                SAVE BINARY FILE
This  will  prompt  for  a  filename,  a  start  address  and  an
(inclusive) end address.  To re-save a file recently loaded  with
the above command <filename>,M0,M1 may be specified,  assuming of
course that M0 and M1 may be specified,  assuming of course  that
M0 and M1 have not been re-assigned.

A                                                 LOAD ASCII FILE
This  powerful command allows an ASCII file,  normally of  source
code,  to  be loaded and viewed within Monam,  Window 4  will  be
created if required then set up as a source code  window.  Memory
for  the  source  code is taken from the system so sufficient free
memory must be available.

EXECUTING PROGRAMS

Ctrl-R                                    RETURN TO PROGRAM / RUN
This  runs the current program with the given register values  at
full speed and is the normal way to resume execution after  entry
via a breakpoint.

Ctrl-Z                                                SINGLE-STEP
This  single-steps  the instruction at the PC  with  the  current
register values.  Single-stepping a Trap, Line-A or Line-F opcode
will, by default, be treated as a single instruction. This can be
changed using Preferences.

Ctrl-Y                                                SINGLE-STEP
Identical  to  Ctrl-Z above but included for the  convenience  of
German users.

Ctrl-T                           INTERPRET AN INSTRUCTION (TRACE)
This  interprets  the instruction at the PC using  the  displayed
register  values.  It is similar to Ctrl-Z but skips  over  BSRs,
JSRs, Traps, Line-A and Line-F calls, re-entering the debugger on
return from them to save stepping all the way through the routine
or trap it works on instructions in ROM or RAM.

Ctrl-S                                        SKIP AN INSTRUCTION
Ctrl-s increments the PC register by the size of the current
instruction thus causing it to be skipped. Use this instead of Ctrl-Z
when you know that this instruction is going to do something it
shouldn't.

R                                                   RUN (VARIOUS)
This is a general Run command and prompts for the type of the Run
to be done, selected by pressing a particular key.

Run    G  GO
This  is  identical to Ctrl-R,  and resumes the program  at  full
speed.

Run    I  Instruction
This executes the entered number of instructions remembering
information in the history buffer and then returning to monam.

Traps will be treated as single-instructions.

SEARCHING MEMORY

G                                  SEARCH MEMORY (GET A SEQUENCE)
This  will  prompt Search for  B/W/L/T/I?,  standing  for  Bytes,
Words, Longs, Text and Instructions.
     If  you select B, W or L you will then be prompted to enter  the
sequence  of numbers you wish to search for,  each  separated  by
commas.  MonST is not fussy about word-alignment when  searching,
so it can find longs on odd boundaries, for example.
     If you select T you may search for any given text  string,  which
you will be prompted for. The search will be case-dependent.
     If you select I you can search for part or all of the mnemonic of
an instruction,  for example if you searched for $14 (A you would
find  an  instruction like MOVE.L D2,$14(A0).  The  case  of  the
string you enter is important (unlike Monam version 1),  but  you
should  bear in mind the format the disassembler  produces,  e.g.
always use hex numbers, refer to A7 rather than SP and so on.
     Having  selected  the  search type  and  parameters,  the  search
begins, control passing to the Next command, described below.

N                                                       FIND NEXT
     This can be used after the G command to find subsequent
ccurences of the search data.  With the B,  W, L and T options you
will always find at least one occurrence,  which will be in the buffer
within MonAM that is used for storing the sequence.  With the  T
option you may also find a copy in the system keyboard  buffer.
With these options, the Esc key is tested every 64k bytes and can
be used to stop the search.  With the be used to stop the search.
With  the I option,  which is very much slower,  the Esc  key  is
tested every 2 bytes.
     The  search area of memory goes from 0 to the end of chip memory,
then from $F80000 to $FFFFFF (the ROM), then any additional RAM.
     The search will start just past the start address of the  current
window  (except register windows) and if an occurrence  is  found
re-display the window at the given address.

SEARCHING SOURCE-CODE WINDOWS
     If  the  G  command is used on a source-code window  the  T  sub-
command  is  automatically chosen and if the text  is  found  the
window will re-display the line containing it.

MISCELLANEOUS

Ctrl-P                                                PREFERENCES
This permits control over various options within MonAM. The first
three require Y/N answers,  pressing Esc aborts or Return  leaves
them alone.

RELATIVE OFFSETS
     This  option  defaults to On and effects the disassembly  of  the
address  register  indirect with offset  addressing  modes,  i.e.
xxx(An).  With  the  option  on the current value  of  the  given
address register is added to the offset then searched for in  the
symbol table.  If found it is disassembled as symbol  (An).  This
option  is  very useful for certain styles of  assembly  language
programming  as  well as high level languages which  use  a  base
register as a major offset, such as HiSoft BASIC which uses A3 as
a pointer to the run-time system.

SYMBOLS OPTION
     This  allows  control over the use of symbols in  expressions  in
MonAm.  It will firstly ask whether the case of symbols should be
ignored,  pressing Y will cause case independent searching to  be
used.  It  will  then prompt for the maximum length  of  symbols,
which is normally 32 but may be reduced to as low as 8. Or increased
if required.

PRINTER DEVICE
     This lets you set the device that Monam uses for its printer
commands, the default is PRT:

SAVE PREFERANCES
     Reply Y to this command to save your current preferances to the
file monam2.inf in the current directory. When monAm2 loads it will
read your current preferances from this file. Monam2.inf is firstly
searched for in the current directory, then in the c: directory, in a
similar way to the editor preferances file.

I                                                INTELLIGENT COPY
This  copies  a block of memory to another  area.  The  addresses
should be entered in the form:

        <start>,<inclusive end>,<destination>

     The copy is intelligent in that the block of memory may be copied
to a location which overlaps its previous location.
     NOTE:  No  checks at all are made on the validity  of  the  move;
copying to non-existent areas of memory is likely to crash Monam
and corrupting system areas may well crash the machine.

L                                                     LIST LABLES
This opens up a large window and displays all loaded symbols. Any
key displays the next page, pressing Esc aborts. The symbols will
be  displayed  in the order they were found on the  disk  (or  in
memory if using the Debug option from the editor).

Ctrl-U name                                        UNLOAD SYMBOLS
This command can only be used if you are debugging a task which had a
symbol table loaded with it. What it does is de-allocate the memory
used for storing symbols, freeing it for the system to use. This can
be very useful if memory is tight while debugging a lager program, as
you can load it, together with symbols, set a breakpoint at a symbolic
address, then lose the labels before letting it run. Of course once
you hit your breakpoint you won't have any symbols.
     NOTE: Thois command used to be Ctrl-L on Monam version 1.

COMMAND SUMMARY

WINDOW COMMANDS
(AMIGA)-A ..................... Set Address
(AMIGA)-B ..................... Set Breakpoint
(AMIGA)-E ..................... Edit Window
(AMIGA)-L ..................... Lock Window
(AMIGA)-O ..................... Show Other
(AMIGA)-P ..................... Printer Dump
(AMIGA)-R ..................... Register Set
(AMIGA)-S ..................... Split Windows
(AMIGA)-T ..................... Change Type
(AMIGA)-Z ..................... Zoom Window

BREAKPOINTS
(AMIGA)-B ..................... Set Breakpoint
Help ...................... Show Help and Breakpoints
Ctrl-B .................... Set Breakpoint
U ......................... Go Until
Ctrl-K .................... Kill Breakpoints
Ctrl-A .................... Set Breakpoint then Execute
Ctrl-X .................... Stop program executing

LOADING AND SAVING
Ctrl-L .................... Load Executable Program
B ......................... Load Binary File
S ......................... Save Binary File
A ......................... Load ASCII File

EXECUTING PROGRAMS
Ctrl-R .................... Return to program/Run
Ctrl-Z .................... Single-Step
Ctrl-Y .................... Single-Step
Ctrl-T .................... Interpret an Instruction (Trace)
Ctrl-S..................... Skip instruction
R ......................... Run (various)

SEARCHING MEMORY
G ......................... Search Memory (Get a sequence)
N ......................... Find Next

MISCELLANEOUS
Ctrl-C .................... Terminate
Ctrl-Q..................... Quit program
Ctrl-P .................... Preferences
I ......................... Intelligent Copy
W ......................... Fill Memory With
L ......................... List Labels
Ctrl-U..................... Unload symbols
P ......................... Disassemble to Printer/Disk
M ......................... Modify Address
O ......................... Show Other Bases
D ......................... Change Drive & Directory
H ......................... Show History Buffer
V.......................... View other screen

DEBUGGING STRATAGEM

RESTRICTIONS
     As it runs as a process MonAm relies on the exec.intuition and
graphics libraries. If your program starts destroying memory to which
it has no right it is possible for it to fatally corrupt something the
system needs so that when monam is entered after an exception the
machine will crash. Fortuanely this type of error is rare, usually
address errors occur before programs start destroying memory.
     When a program is invoked from Monam it is set up to look as if
it has been run from the CLI, not the workbench.
     Monam cannot single step or breakpoint any code when executing in
supervisor mode. This is because the exec exception handler checks for
an execption in supervisor mode, amd will put up a guru alert if this
is the case. If not it will enter Monam and work normally.
     If your program creates another program or task you cannot use
monam to breakpoint it or single-step. Monam can only debug the
program that was specified when it initially loaded.
     Don't try and run the standard system programs from within Monam,
such as dir. These rely on undocumented registers (particually a5) and
memory areas which monam cannot emulate.
     Due to a hardware feature, a word - or longword-access on odd
memory locations 1 to 7 inclusive will cause a complete machine crash.
There seems to be nothing we can do to prevent this.

BUG HUNTING
     There  are probably as many strategies for finding bugs as  there
are programmers;  there is really no substitute for learning  the
hard way,  by experience.  However, there are some hints which we
have learnt, the hard way!
     Firstly, a very good way of finding bugs is to look at the source
code  and  think.  The  disadvantage of reaching  first  for  the
debugger,  then second for the source code,  is that it gets  you
into  bad  habits.  You may switch to a  machine  or  programming
environment that does not offer low-level debugging,  or at least
not one as powerful as you are used to.
     If a program fails in a very detectable way,  such as causing  an
exception,  debugging is normally easier than if,  say, a program
sometimes doesn't quite work exactly as it should.
     Many  bugs  are  caused by a  particular  memory  location  being
stepped on.  Whether the offending memory location is detectable,
by producing a bus error,  for example,  a conditional breakpoint
placed  at  one or more main subroutines can  help  greatly.  For
example, suppose the global variable main_ptr is somehow becoming
odd during execution,  the conditional expression could be set up as:

(main_ptr)&1

     Count  breakpoints  are a good way of tracking down  bugs  before
they occur. For example, suppose a particular subroutine is known
to eventually fail but you cannot see why,  they you should set a
count breakpoint on it,  then let the program run.  At the  point
where the program stops, because of an exception say, look at the
value  of  the  count  breakpoint  (using  Help).  Terminate  the
program, re-load it, then set a stop breakpoint on the subroutine
for that particular value or one before it.  Let it run, then you
can  follow  through  the sub-routine on the very  call  that  it
fails on, to try and work out why.                      GOOD LUCK!

EXCEPTION ANALYSIS
     When an unexpected exception occurs,  it's very useful to be able
to work out where and why it occurred and,  possibly,  to  resume
execution.

BUS ERROR
     If the PC is in some non-existent area of memory then look at the
relevant stack to try and find a return address to give a clue as
to  the cause,  probably an unbalanced stack.  If the PC is in  a
correct  area of your program then the bus error must  have  been
caused  by a memory access to non-existent or  protected  memory.
Recovering  from bus errors and resuming execution  is  generally
not possible.

ADDRESS ERROR
     If  the PC is somewhere strange the method above should be  used,
otherwise the error must have been caused by a program access  to
an  odd  address.  Correcting a register value may be  enough  to
resume execution, at least temporarily.

ILLEGAL INSTRUCTION
     If the PC is in very low memory, below around $30, it is probable
that it was caused by a jump to location 0.  If you use MonAM to
look  here  you will normally see various ORI instructions  (really
longword   pointers)   and eventually an illegal instruction.

PRIVILEGE VIOLATION
     This  is  caused by executing a privileged  instruction  in  user
mode,  normally  meaning  your program has gone  horribly  wrong.
Bumping  the PC past the offending instruction is unlikely to  be
much help in resuming the program.

APPENDIX A: AmigaDOS error codes
     This appendix details the numeric AmegaDOS errors and their
meanings:

103     insufficient free store                 out of memory
104     task table full                         limit of 20 cli's
120     argument line invalid or too long       when using CLI commands
121     file is not an object module            trying to execute a non-
                                                executable file
122     invalid resident library during load
202     object in use                           such as a file by another
                                                program
203     object already exists
204     directory not found
205     object not found                        most commonly a file
206     invalid window                          in name specification
209     packet request type unknown
210     invalid stream component name           name too long or contains
                                                control characters
211     invalid object lock
212     object not of required type             such as directory name
                                                instead of file
213     disk not validated                      disk is still being
                                                validated, or is bad
214     disk write-protected
215     rename across devices attempted
216     directory not empty                     when trying to delete it
218     device not mounted                      after specifying a volume
                                                name
219     seek error
220     comment too big                         file comments must be
                                                less than 80
221     disk full
222     file is protected from deletion
223     file is protected from writing
224     file is protected from reading
225     not a DOS disk
226     no disk in drive
232     no more enteries in directory

APPENDIX B: GenAM error messages
     Genam can produce a large number of error messages, most of which
are  pretty  self explanatory.  This appendix lists them  all  in
alphabetic  order,  with clarifications for those  which  require
them.
     Please note that GenAM is continually being improved and list may
not  agree  exactly  with the version  you  have,  there  may  be
additional messages not documented here.

ERRORS
     If you get a message beginning with INTERNAL please tell us - you
should never see these.

.W or .L expected as index size

absolute expression MUST evaluate

absolute not allowed

additional symbol on pass 2
            somehow a symbol has appeared during pass 2 that  did
            not appear during pass 1

address register expected

addressing mode not allowed

addressing mode not recognised

BSS or OFFSET cannot contain data
            OFFSET  sections  and non-GST BSS sections  can  only
            contain DS directives

cannot create a binary file
            could be a bad filename,  or a write-protected  disk,
            etc.

cannot export symbol

cannot import symbol

cannot reset MACRO definitions or define in REPTs
            macro definitions may not be nested or defined within
            repeat loops

cannot nest repeat loops

comma expected

data register expected

data too large

division by zero

duplicate MODULE name

module names must be unique

error during listing output
            listing will be stopped at this point

error during writing binary file
            normally disk full

executable code only
            only executable code may be assembled to memory

expression mismatch
            normally a syntax error within an expression

fatally bad conditional
            there were more ENDCs in a macro than IFs

file not found

forward reference

garbage following instruction

illegal BSR.S
            a BSR.S to the following instruction is not allowed -
            change it to BSR

illegal type combination

immediate data expected

imported label not allowed

include file read error

instruction not recognised

invalid FORMAT parameter

invalid INCDIR
            You have used more than 500 bytes of directory
specifications

invalid IF expression, ignored

invalid MOVEF addressing mode

invalid number

invalid numeric expression
            the  symbol  is not defined or relative or  a  syntax
            error

invalid option

invalid printer parameter

invalid register list

invalid section name, TEXT assumed

invalid size

line malformed

linker format restriction
            the AmigaDOS format is restrictive about where it  allows
            imports

local not allowed

missing close bracket

missing ENDC
            there were more IFs than ENDCs

missing quote

misuse of label

not yet implemented

number too large

odd address

option must be at start

ORG not allowed

out of memory

phasing error
            should  never happen,  look  investigate  immediately
            before first such error

program buffer full
            change  the  program buffer size when  assembling  to
            memory

register expected

relative not allowed

relocation not allowed

repeated include file

each include file may only be included once on each pass

source expired prematurely
            with an IF, MACRO or REPT and the source ran out

spurious ENDC

spurious ENDM or MEXIT

spurious ENDR

symbol defined twice

symbol expected

undefined symbol

user error
            caused by FAIL directive

wrong processor

XREFs not allowed within brackets

WARNINGS
68010 instruction, converted to MOVE SR
            MOVE CCR, is not a 68000 instruction

branch made short
            by optimising

directive ignored

invalid LINK displacement
            if negative or odd

offset removed
            xx(An) form reduce to (An) by optimising

relative cannot be relocated

short branch converted to NOP

sign extended operand
            data in MOVEQ needed sign extension to fit

size should be .W

APPENDIX C: CALLING THE OPERATING SYSTEM

INTRODUCTION
     The Amiga operating system is arguably with the exception of OS/2
the most sophisticated of any mass produced computer, and is also the
most complicated. The whole machine is based around the concept of
libraries, which are essentially groups of subroutones (or functions
to C-programmers) indexed off a large jump block. The appendix is
intended to explain the basics of calling libraries from assembly
language, and to give an idea of what each can be used for. One small
Appendix cannot possibly describe the whole operating system, it is
only meant as an introduction.
    Please note that was written with version 1.2 of Kickstart in
mind, it is possible subsiquent versions may differ slightly. Any
important differances should be detailed in the readme file.

LIBRARIES
     The most basic library is the exec library, which has to be
called to open nay other library, among other things. As with all
libraries, a library base pointer is required to access it, and this
must be loaded into register a6 before calling any function. The exec
library is unique as that it dosen't have to be opened to obtain a
base pointer - this can be obtained from the longword at location 4 -
the only location in the whole machine guaranteed to remain the same
in the future. The base pointer so obtained can then be used to open
further libraties, to obtain other library base pointers, and so on.
Note that most libraries require a6 to be contained in the base
pointer for correct operation (as they call the other routines in the
same library) though not all do. Parimiters are passed to library
routines in requesters, and sa a general rule requesters d0/d1/a0/a1
should be assumed to be corrupted by any call.
     A large number of include files are supplied with DEVPAC to allow
easy access to the various parts of the opearting system. These
include files containing macro definitions, library offset symbols,
data structure definitions, and bit field symbols. There now follows a
library table showing the names of the various components, and where
the definitions can be found in the include directory.

FILE: this shows the file that contains the macro definitions and _LVO
offsets for calling the library.

NAME MACRO: this normally consists of a dc.b statement defining the
ASCII for the name, ending in a null.

BASE POINTER: this is the symbolic name of the longword used for
storing the base pointer. It always starts with an underline
character, though when used from most C compilers this underline is
not shown.

CALLING MACRO: this is the name of the macro that calls a particular
library. Note that this will corrupt register a6 as it will be loaded
with the relevant library base pointer.

LIBRARY         FILE                            NAME MACRO
                        BASE POINTER                    CALLING MACRO
diskfont        libraries/diskfont_lib.i        DISKFONTNAME
                        _DiskfontBase                   CALLDISKFONT
dos             libraries/dos_lib.i             DOSNAME *
                        _DOSBase                        CALLDOS
exec            exec/exec_lib.i                 EXECNAME
                        _SysBase                        CALLEXEC
expansion       libraries/expansion_lib.i       EXPANSIONNAME **
                        _ExpansionBase                  CALLEXP
graphics        grapgics/graphics_lib.i         GRAFNAME
                        _GfxBase                        CALLGRAF
icon            workbench/icon_lib.i            ICONNAME
                        _IconBase                       CALLICON
intuition       intuition/intuition_lib.i       INTNAME
                        _IntuitionBase                  CALLINT
mathffp         math/mathffp_lib.i              FFPNAME
                        _MathBase                       CALLFFP
mathdouble      math/mathieeedoubas_lib.i       IEEEDOUBNAME
                        _MathIeeeDouBasBase             CALLIEEEDOUB
mathtrans       math/mathtrans_lib.i            MATHTRANSNAME
                        _MathTransBase                  CALLMATHTRANS
translator      libraries/translator_lib.i      TRANSNAME
                        _TranslatorBase                 CALLTRANS

     For example, to call the exec library function OpenLibrary
suitable assembler source code would be

        CALLEXEC    OpenLibrary

This macro is expanded into

        move.l      (_SysBase).w,a6
        jsr         _LVOOpenLibrary(a6)

 * = name macro definition can be found in file libraries/dos.i
** = mane macro can be found in file libraries/expansion.i

DISKFONT LIBRARY:
     This is a library for handling fonts that are normally resident
on the disk.
FILES: libraries/diskfont.i and diskfont_lib.i

DOS LIBRARY:
     One of the most straightforward of the libraries to use, this
handles file i/o (input/output) to devices, including disk and
console. It has some slight anomalities, notabily addersses have to be
passed in data registers, and many pointers have to be BCPL-type (ie.
longword aligned and divided by 4)
FILES: libraries/dos.i  dos_lib.i and dosextens

EXEC LIBRARY:
     This is the lowest level of library, responsible for things like
memory management, library calls, and message passing. The library
never has to be opened - its base pointer is contained in location 4.
FILES: exec/ables.i  alerts.i  devices.i  errors.i  exec.i  execbase.i
execname.i  exec_lib.i  funcdef.i  initializers.i  interrupts.i  io.i
libraries.i  lists.i  memory.i  nodes.i  ports.i  resident.i
strings.i  tasks.i  and types.i

GRAPHICS LIBRARY:
     This is responsible for controlling exectly what appears on your
monitor, including things like drawing lines, printing text,
controlling RastPorts, sprite handling and fonts.
FILES: graphics/clip.i  copper.i  display.i  gels.i  gfx.i  gfxbase.i
graphics_lib.i  layers.i  rastport.i  regions.i  sprite.i  text.i  and
view.i

ICON LIBRARY:
     This library is responsible for handling the icons displayed by
the Workbench.
FILES: workbench/icon.i  icon_lib.i

INTUITION LIBRARY:
     This library is the lagest and is responsible for the windowing
intuition user interface. It has a very large number of functions,
including those for window conrtol, screens. gadgets, requesters, and
event handling.
     The main file is large and also includes a large number of other
files, so don't be surprised if it takes a little while to read it
all. It can be worthwile to create your own specilised version without
the less-often used constants, which can reduce the amount of other
include files required.
FILES: intuition/intuition.o  and intuition_lib.i

MATHS LIBRARIES:
     There are three maths libraries, all based on the official
Motorola routines. The FFP (Fast Floating Point) library uses an 8-bit
exponent, 24-bit mantissa format. The format used was designed for the
68000 series, and is exclusive to Motorola. The IEEE double library
offers doublr-precision using IEEE standard formats for numbers, and
the Trancendental library is used for FFP trig and other functions.
FILES: math/mathffp_lib.i  mathieeedoubbas_lib.i  and  mathtrans_lib.i
     As a genaral rule you should use GenAm in case sensative mode
(the default) when using the supplied include files. note that every
include file always includes any others it needs automatically, so you
don't need to worry about it.

EXAMPLE PROGRAMS
    To help you get started programming AmigaDOS from assembly
language we have provided the source to a few example programs in the
examples directory.

DEMO.S
     this is the program used for the tutorial at the beginning of the
manual. It uses the DOS library to print a message on the current CLI
window.

FREEMEM.S
    This program that uses intuition to create a window in which the
system free memory is constantly displayed, until the close gadget is
clicked on. To run this concurrently from the CLI use the command:

run examples/freemem

HELLOWORLD.S
     This is the assembly language conversion of the C program 'final
version of the simple program' described at the beginning of
'intuition - the amiga user interface'. The conversion has not been
optimised in any way, for example, the structure assignment for
NewScreen would be more efficient using dc.w/dc.l statements, but has
been left as MOVE instructions for a more accurate conversion. The
program opens up a custom screen and, within it, a simple message.

CLI vs WORKBENCH
     There are two program enviroments on the amiga - the windows &
icon driven workbench, and the CLI. Devpac itself runs only under the
latter, as do most example programs, the differance being in the
startup and exit code.

CLI STARTUP
     When a program is run from the CLI it starts with register a0
containing the address of the command linem and d0 containing its
length. The DOS handles returned by input and output can be used for
i/o with the console device, and to exit the program should simply
RTS.

WORKBENCH STARTUP
     When a program is run from the Workbench it has to wait firstly
for a message, and on terminating it has to reply to the message
(after doing a forbid call) before RTSing. The DOS functions input and
output will not return valid handles, so you need to open a window to
perform any console i/o
     the startup differances are detailed in part 4, chapter 2 of the
ROM Kernal Menual Volume 1, together with the assembly language source
of the startup code used by C programs. Note that there is a bug in it
- the routine openDOS should have a moveq #0,d0 instruction added
before the call to OpenLibrary, otherwise a fatal alert can be
produced.
     A skeleton version of this for assembly language programmers can
be found in the file misc/easystart.i which is included by the
freemem2.s example program. It should be included at the very front of
your programs, and handles the message-passing to allow programs to be
run from workbench. Of course to do this you will need to create an
icon for your program, using iconed.

APPENDIX D: USING THE CLI
     All this section is covered in the Amiga manuals you get with the
machine so look them up yourselves!

APPENDIX E: CONVERTING FROM OTHER ASSEMBLERS
     Most 68000 assemblers for the Amiga follow, to one degree or
another the Motorola standard. While the instructions themselves  are
thankfully standard,  the syntax rules for labels,  comments  and
directives can,  and do,  vary.  This Appendix covers the changes
most  likely  to be made when converting  programs  from  another
assembler,  whether  they are your old source files or a  program
listed  in  a  magazine.  It  does  not  attempt  to  detail  the
differences  in user interfaces or options between the  different
assemblers.

AMIGA MACRO ASSEMBLER AND MCC ASSEMBLER:
     Almost all source code written for assembly under the Amigados
Macro Assembler supplied by Commodore and the Metacomco (MCC)
assembler should assemble with little or no change under GenAm. The
differances are:

1. With GenAm, importing constants using XREF and then accessing them
as constants (as opposed to relative addresses) may cause warning
messages. Many source programs use XREFs for _LVO labels. To remove
these warnings either:

change XREF to XREF.l
use OPT W- to supress all warnings
use OPT T- to suppress type-checking
include the relevant _lib.l file and remove the XREF

2. The directive RORG is not supported. The include files with the
AmigaDOS Macro Assembler will assemble unchanged by GenAm, but our
supplied ones are preferred because they use directives instead of
macro calls to define labels and have comments removed to take less
disk space and be faster to assemble. The original versions can be
found in Appendix E of ROM Kernal Manual Volume 2 and on DEVPAC disk
2.

K-SEKA:
     Colons are not required after labels in GenAm though instructions
or directives that start in the label field will need a tab added
before them.  Several Seka directives default to Byte instead  of
Word sizes for some reason. Equivalent directives names are:

D=DC,  BLK=DS,  IF=IFNE,  ELSE=ELSEIF, ENDIF=ENDC.

Macro syntax requires ?s to be changed to \s, except ?0 which should
be replaced with \@.

NEW COMMODORE INCLUDE FILES
     Should you obtain new include files from Commodore you should be
able to assemble them unchanged with GenAm. however should you wish to
convert them to the same form as those supplied by us so that they
take less disk space, and assemble faster, we have supplied two tools
to convert them for you, 'convertFD' and 'convertI'

CONVERTI DETAILS:
     Converti is supplied on disk 2 and converts Commodore include
files to the same compressed form that we supply. The commandline is
of the form:

ConvertI (source) (destination) <-d>

     The source and destination file names should have their extension
omitted. Teh -d flag indicates that a whole directory is to be
converted. For example:

ConvertI old/dos new/dos

converts the single file old/dos.i to new/dos.i

ConvertI old new -d

will convert all the standard files in the directory old (of course
they must be there first) to the corresponding name in the directory
new.

CONVERTFD DETAILS:
     ConvertFD is supplied on disk 2 and converts Commodore FD files
into library files with extension _lib.i containing the_LVO offsets
for inclusion into your programs.
     The command-line is of the form:

ConvertFD (source) (destination) <-d)

     The source and destination file names should have their
extensions onitted. The -d flag indicates that a whole directory is to
be converted. For example:

ConvertFD fdfiles/dos new/dos

converts the single file fdfiles/dos_lib.fd to new/dos_lib.i

ConvertFD fdfiles :include/libraries -d

will convert all the fd files in the directory fdfiles (of coures they
must be there first) to the corrosponding include file in the
directory :include/libraries.

APPENDIX F: VERSION 2 IMPROVEMENTS
     All information is already documented earlier.

APPENDIX G: BIBLIOGRAPHY
     This bibliography contains our suggestions for further reading on
the subject of the 68000 and the Amiga.  The views expressed
are  our  own  and  as  with all  reference  books  there  is  no
substitute  for  looking at the books in a good  bookshop  before
making a decision.

M68000 Programmer's Reference Manual
Published by Prentice-Hall
The definitive guide to the instruction set produced by Motorola.
the  supplied Pocket Guide is a subset of this book.  Be sure  to
get the latest version - at the time of writing the Fifth Edition
is the latest.

68000 Assembly Language Programming by Kane, Hawkins & Leventhal
Published by Osborne/McGraw-Hill
This  is  large  (and expensive) but  good,  containing  lots  of
examples.  Be  sure to get the second edition.  Not for  complete
beginners to microprocessors.

68000 Tricks and Traps by Mike Morton
BYTE magazine, September 1986 issue
By  far the best article on 68000 programming we have ever  seen.
We wish there was a book like this.

M68000 Cross Macro Assembler Reference Manual
Published by Motorola (M68KXASM)
The  official  definition of 68000  assembly-language  syntax  on
which Genam is based.

APPENDIX H: TECHNICAL SUPPORT AND UPGRADES
      Which is no use to you as your not a registered user!.